home *** CD-ROM | disk | FTP | other *** search
/ HPAVC / HPAVC CD-ROM.iso / STK100.ZIP / STKMAN.DOC < prev    next >
Text File  |  1995-02-28  |  90KB  |  2,598 lines
  1.                 DiamondWare's Sound ToolKit
  2.  
  3. Welcome to DiamondWare's Sound ToolKit (STK).  If you're a game or
  4. multimedia developer or programmer, and you want a hassle-free, easy
  5. way to include high-quality music and digitized sound effects in
  6. your products, and you don't want to pay high licensing fees or
  7. ongoing royalties, you've come to the right place.
  8.  
  9. My name is Dave Snyder, and I'm the President of MVP Software.  I'd
  10. like to tell you a little about this product and why we're so
  11. excited about it.
  12.  
  13. Q: Why is MVP Software Publishing a Programmer's Toolkit?  I thought
  14. you guys published games?
  15.  
  16. MVP is indeed a game publisher.  As such, we are always on the
  17. lookout for ways to make our games better.  Frankly, until now we
  18. had never found any sound drivers with which we were happy.
  19. Although we've tried most of them, and used some of them, there were
  20. always problems.
  21.  
  22. For one thing, I don't want our games littering users' hard drives
  23. with zillions of tiny files.  For another, I want our games to work.
  24. Period.  I want them to work with all the sound cards out there.  I
  25. want our games to work on IRQs 2, 7, and 10, the notorious "problem"
  26. IRQs.  I want the sound card setup to be completely transparent to
  27. my users.  Many of our users don't even know what sound cards they
  28. have installed in their systems, let alone what IRQ or DMA it's
  29. installed on.  I want our sound drivers to handle all that stuff
  30. reliably and automatically.
  31.  
  32. In addition, I want our games to sound great.  I want haunting
  33. melodies, growling sound effects, and realistic reproduction.  I
  34. don't want the sound drivers to take much memory, and I definitely
  35. don't want them to sap speed from our games.  I want our DOS games
  36. to work in a Windows or OS/2 DOS box.
  37.  
  38. One other thing.  I don't want MVP programmers to take all their
  39. time learning how to use sound drivers.  I want the API to be clean
  40. and the implementation as painless as possible.  And I want the
  41. sound drivers to work fine in C/C++, Assembly, Pascal, and BASIC.
  42.  
  43. Q: It sounds like you want a miracle!
  44.  
  45. Yep, and that's why we're publishing DiamondWare's Sound ToolKit.
  46. This product does all these things and more.  We've begun
  47. implementing it in our games.  Already we have implemented it in
  48. games written in C, Pascal, and BASIC.  We've conducted user beta
  49. tests of these games.  In fact, we were so pleased with its
  50. performance that we arranged to publish it and make it available to
  51. other developers.
  52.  
  53. So if you want great sound in your games, you want easy
  54. implementation, and you want to produce a game even a Kmart shopper
  55. can install and use without calling tech support, give DiamondWare's
  56. Sound Toolkit a run for its money.
  57.  
  58. Q: Can I try out DiamondWare's Sound ToolKit before I buy it?  I want
  59. to see for myself that everything you say about it is true!
  60.  
  61. You bet.  That's why we have released this fully-functional demo.
  62. You have everything you need right now to implement the STK in your
  63. game or application and put it through its paces.  All the functions
  64. and functionality is included in this demo.  We're so sure that
  65. after you try this you'll want the full product, that we're not
  66. hiding anything!  Heck, our docs even describe its limitations.
  67.  
  68. We only ask two things.  First, try the STK for 30 days.  If you
  69. like it, buy the full DiamondWare's Sound ToolKit directly from MVP.
  70. The price is only $299.95, and there are no additional fees or
  71. royalties to pay.  You get unlimited technical support too.  Second,
  72. tell your programmer friends about the STK and give them this demo.
  73.  
  74. Q: When I buy the full STK, what do I get?
  75.  
  76. Well, first of all, you get the complete product without those
  77. beginning and ending sound effects that you hear in this demo.  We
  78. know you're honest, but we weren't sure about everyone else. <g>
  79. Seriously, this is a demo, not a free toolkit, and we put those
  80. sound effects in there so everyone knows that right away.  So when
  81. you purchase the full STK, you get a fully useable product.
  82.  
  83. Second, you get an excellent printed manual.  Our manual is the best
  84. sound toolkit manual there is.  We've included full file
  85. specifications on our .dwd and .dwm file formats.  We've even
  86. included a chapter on aesthetic and design considerations of music
  87. and sound in games, written by a published professional musician in
  88. the field.
  89.  
  90. Third, you get an extra .ibk file.
  91.  
  92. Fourth, you get $287 of bundled software.  Yep, that's right, you
  93. pay us $299.95 for the STK, and we include not only the STK drivers,
  94. the docs, and the extra .ibk file, but we include $287 of additional
  95. software.
  96.  
  97. Q: Cool!  What extra software do I get?
  98.  
  99. Well, if you're serious about music and sound effects in your
  100. product, you'll need a FM editor and a digitized sound editor.
  101. We've bundled two of the best with the STK, Flashpoint Production's
  102. Symphonix OPL FM Patch Editor and Sonic Foundry's Sound Forge 2.0.
  103. And these aren't shareware versions or demos, but full retail
  104. products, including their own manuals.  Both are Windows programs,
  105. and if you were to buy them separately (both are widely available),
  106. you would spend $218.90 for the software.
  107.  
  108. But that's not all.  When you purchase the full STK, you also
  109. receive a CD of 300 sound effects.  This CD has a list price of
  110. $69.95.  The sound effects can be included in your game for no
  111. additional licensing fees or royalties.  These are not public domain
  112. or shareware sound effects, but professional files.
  113.  
  114. Q: OK, I'm convinced.  How do I order?
  115.  
  116. I thought you might ask that. <g>  From the United States or Canada,
  117. call our 24-hour order hotline at 800-968-9684.  Have your Master
  118. Card or Visa ready, and ask for DiamondWare's Sound ToolKit.  If you
  119. prefer to email an order, send email to Dave Snyder on Compuserve at
  120. 74777,1116.  We'll need your name and address and credit card number
  121. and expiration date to fill your order.  And please, the 800 number
  122. is an order line only.  The folks who take your order barely know
  123. how to use a computer, let alone answer technical questions.  If you
  124. want support or have questions, call 616-245-8376.
  125.  
  126. Alternatively, print out the ORDER.FRM file included with this
  127. demo version, fill it out, and mail it with a check to MVP Software,
  128. 1035 Dallas SE, Grand Rapids, MI 49507-1407.  Or fax it (don't forget
  129. your credit card info) to 616-245-3204.
  130.  
  131. Overseas orders and support, call 616-245-8376.
  132.  
  133. Legal Stuff and credits (boring, but important -- please read it)
  134. -----------------------------------------------------------------
  135. DiamondWare's Sound ToolKit (STK) was designed and developed by
  136. DiamondWare, Ltd. and is marketed and distributed exclusively by
  137. MVP Software, Inc.
  138.  
  139. This software and documentation are Copyright 1994 DiamondWare, Ltd.
  140. All rights reserved.  DiamondWare's Sound ToolKit, DiamondWare's
  141. STK, The STK, DiamondWare, and DW are trademarks of DiamondWare,
  142. Ltd.
  143.  
  144. DiamondWare can be contacted via:
  145.    FAX/BBS: (914) 638-6942
  146.    email:   keith@dw.com
  147.  
  148. MVP can be contacted via:
  149.    FAX:   (616) 245-3204
  150.    email: 74777.1116@compuserve.com
  151.  
  152. DiamondWare's Sound ToolKit was designed and developed by Keith
  153. Weiner and Eric Lorenzen.
  154.  
  155. Example source code was developed by Erik Lorenzen and Keith Weiner,
  156. with language-specific help from David Johndrow (Pascal), and Don
  157. Lemons (BASIC).
  158.  
  159. This document was written by Keith Weiner, with major revisions by
  160. Eric Lund, and a chapter on music/sound development by David
  161. Schultz.  David is a professional musician and has produced music
  162. for several published games.  You can contact David via CompuServe:
  163. 72143,3624.
  164.  
  165. Included sample MIDI song is Copyright 1994 David Schultz, All
  166. Rights Reserved.  Used by permission.  May not be used without
  167. written permission from David Schultz.
  168.  
  169. Proofreading was done by Joyce Peterson, David Ziegler, and Erik
  170. Lorenzen.
  171.  
  172. Miscellaneous utility programs which made the STK possible were
  173. written by David Ziegler.
  174.  
  175. The included FM instrument patch file is courtesy of Rob Wallace of
  176. Wallace Music and Sound.  Rob is a professional musician and has
  177. produced music and sound for many published games.  You can contact
  178. Rob via CompuServe: 71042,1410.
  179.  
  180. Special thanks to Steve Blackwood, John Davis, Steve Estvanik, David
  181. Johndrow, Don Lemons, and David Schultz for testing.
  182.  
  183.  
  184. 386MAX is a trademark of Qualitas Inc.
  185. Advanced Gravis and Ultrasound are trademarks of Advanced Gravis Computer 
  186. Technology Ltd.
  187. AMD is a trademark of Advanced Micro Devices Corporation
  188. Aria is a trademark of Prometheus Products Inc.
  189. Bane is a trademark of Superego Software
  190. Borland and Turbo Pascal are trademarks of Borland International Inc.
  191. Cyrix is a trademark of Cyrix Corporation
  192. IBM and OS/2 are trademarks of International Business Machines Corporation
  193. Intel is a trademark of Intel Corporation
  194. Microsoft, MS-DOS, and Windows are trademarks of Microsoft Corporation
  195. Novell DOS and Novell are trademarks of Novell Inc.
  196. OPL-2 and OPL-3 are trademarks of Yamaha Corporation
  197. QEMM is a trademark of Quarterdeck Office Systems Inc.
  198. Sound Blaster is a trademark of Creative Labs Inc.
  199. TI is a trademark of Texas Instruments Inc.
  200.  
  201.                          LICENSE AGREEMENT
  202.  
  203. This LICENSE AGREEMENT describes the only terms by which we, MVP
  204. Software, of 1035 Dallas SE, Grand Rapids, MI 49507-1407 permit
  205. distribution of this program.
  206.  
  207. Permission is granted to:
  208. ------------------------
  209. Use it for a 30 day trial period, after which you are required to
  210. register with MVP Software by purchasing Diamondware's Sound
  211. ToolKit.  Under no conditions may you redistribute any or all of the
  212. STK without written authorization from MVP Software, except under
  213. the terms below.  This version of the STK may not be distributed as
  214. part of another software product.
  215.  
  216. Non-commercial Distribution
  217. ---------------------------
  218. Distribution is non-commercial if it is for free, or by any
  219. not-for-profit organization, or by hobby, user or computer interest
  220. group to its members, or by any BBS.  Non-commercial distribution is
  221. permitted without further authorization provided the program is NOT
  222. represented as free or public domain.
  223.  
  224. CD-ROM Distribution
  225. -------------------
  226. If you want to distribute this program on a CD-ROM, YOU MUST OBTAIN
  227. WRITTEN PERMISSION FROM MVP SOFTWARE BEFORE DOING SO.
  228.  
  229. Distribution in a Retail Environment
  230. ------------------------------------
  231. If you want to distribute this program in a retail environment, YOU
  232. MUST OBTAIN WRITTEN PERMISSION FROM MVP SOFTWARE BEFORE DOING SO.
  233.  
  234. TERMS OF PERMITTED COMMERCIAL DISTRIBUTION:
  235.  
  236. By "commercially distribute" we mean to distribute for gain,
  237. including by direct mail, catalog, trade show, or flea market.
  238. Distribution by these means is permitted under the terms below.  For
  239. any other form of distribution, YOU MUST CONTACT MVP SOFTWARE FOR
  240. AUTHORIZATION.
  241.  
  242. By "Program" we mean this version and its related files including
  243. this LICENSE.DOC, distributed by us under the Trademark
  244. "DIAMONDWARE'S SOUND TOOLKIT", and as it may be upgraded or
  245. otherwise modified from time to time.
  246.  
  247. A.  OWNERSHIP: Except to the extent expressly licensed by us, we
  248. have and reserve the exclusive copyright and other right, title and
  249. interest to copy and distribute the Program, and the right to use
  250. the Trademark "DIAMONDWARE'S SOUND TOOLKIT" in connection with it.
  251.  
  252. B.  LICENSE: You are licensed commercially to distribute this
  253. program so long as you [1] market it as shareware using "try before
  254. you buy" or similar words, [2] try to sell only the most current
  255. version of it, [3] make distribution copies only from master copies
  256. received from us using high quality disks and duplication
  257. technology, [4] include the words "MVP Software" in every
  258. description of the program that you put in any catalog or other
  259.  
  260. product promotion, and [5] distribute all of its files together in
  261. compressed or other format as released by us, except that you may
  262. add simple introductory or batch files so long as they do not
  263. interfere with or degrade the performance of the program or any
  264. installation file it may contain.
  265.  
  266. C.  THINGS YOU GET: We will provide to you on request [1]
  267. descriptions of the Program's important features which you may
  268. include in catalogs or elsewhere, [2] descriptions of its hardware
  269. prerequisites.  See "VENDOR.DOC" for details.
  270.  
  271. D.  SOME THINGS YOU DON'T GET: Your right to distribute under this
  272. license is personal, and does not include any right to [1]
  273. sublicense or otherwise cause or permit others to copy or distribute
  274. the program without our consent in writing, or [2] distribute it as
  275. part of any hardware or software package.
  276.  
  277. E.  THE PROGRAM IS PROVIDED "AS-IS".  NO WARRANTIES OF ANY KIND,
  278. EXPRESS OR IMPLIED, ARE MADE AS TO IT OR ANY MEDIUM IT MAY BE ON.
  279. WE WILL PROVIDE NO REMEDY FOR INDIRECT, CONSEQUENTIAL, PUNITIVE OR
  280. INCIDENTAL DAMAGES ARISING FROM IT, INCLUDING SUCH FROM NEGLIGENCE,
  281. STRICT LIABILITY, OR BREACH OF WARRANTY OR CONTRACT, EVEN AFTER
  282. NOTICE OF THE POSSIBILITY OF SUCH DAMAGES.
  283.  
  284. H. MISCELLANY
  285.  
  286. 1.  Since we would be irreparably damaged if Sections A. or B. of
  287. this License were breached, we will be entitled without bond, other
  288. security or proof of damages, to appropriate equitable remedies with
  289. respect to such breaches, in addition to such other remedies as we
  290. may have.
  291.  
  292. 2.  You will hold us, our partners, contractors, employees and
  293. agents harmless from damage, loss and expense arising directly or
  294. indirectly from your acts and omissions in copying, distributing or
  295. adding introductory or installation files to the program.
  296.  
  297. 3.  With respect to every matter arising under this License, you
  298. consent to the exclusive jurisdiction and venue of the state and
  299. federal courts sitting in Grand Rapids, Michigan.
  300.  
  301.                  MVP is Now on CompuServe!
  302.  
  303. You can get all of the latest MVP shareware releases, and discuss
  304. MVP titles directly with the authors on MVP's new section on the
  305. world's largest online information network, CompuServe.  Just type
  306. GO MVPSOFT to get to our section!  If you are not a CompuServe
  307. member you are eligible to receive a FREE trial membership,
  308. including software and online time worth almost $55!  That's right,
  309. you get the CompuServe Information Manager software for DOS or
  310. Windows, which normally costs $29.95.  Plus you get a free first
  311. month of online access, worth $9.95.  And to top it off, you get a
  312. usage credit of $15 of additional online time.
  313.  
  314. To take advantage of this free trial membership to the largest
  315. online service in the world, call 800-848-8199.  Ask for rep 671.
  316. And then GO MVPSOFT and talk to the MVP team on CompuServe.
  317.  
  318.                MVP is Now on Delphi Internet!
  319.  
  320. You can get all of the latest MVP shareware releases, and discuss
  321. MVP titles directly with the MVP team on MVP's new Custom Forum on
  322. Delphi Internet.  Just type GO CUSTOM 45 to get to our section!  If
  323. you are not a Delphi Internet member you are eligible to receive a
  324. FREE trial membership, including 5 free hours of online time plus a
  325. free download of InterNav, Delphi's Windows communication software!
  326.  
  327. To take advantage of this free trial membership to Delphi Internet,
  328. follow these instructions:
  329.  
  330.   1.  Dial by modem, 1-800-695-4002
  331.   2.  Press "Return" once or twice
  332.   3.  At the Username prompt, enter JOINDELPHI
  333.   4.  At the Password prompt, enter CUSTOM45
  334.  
  335. Then GO CUSTOM 45 and talk to the MVP team on Delphi Internet.
  336.  
  337.                  MVP is Now on Novalink!
  338.  
  339. You can get all of the latest MVP shareware releases, and discuss
  340. MVP titles directly with the MVP team on MVP's new forum on
  341. NovaLink.  Just type /GO MVPSOFT to get to our section!  If you are
  342. not a NovaLink member you are eligible to receive a FREE trial
  343. membership, including 10 free hours of online time!
  344.  
  345. NovaLink Interactive Network is one of the top 10 US online services
  346. and the first to offer complete multimedia access to the Internet.
  347. NovaLink provides a full slate of online content and discussion
  348. areas, as well as content and links to information and entertainment
  349. on the Internet, all for less than $10 per month.  NovaLink is
  350. accessed via a local call form more than 1,000 US cities and 100
  351. countries.
  352.  
  353. To take advantage of the free trial offer, including 10 free hours
  354. of online time, call 800-274-2814, Web browse to www.novalink.com,
  355. or email info@novalink.com.  Ask for the "MVP Offer" when you call.
  356.  
  357.        MVP is Now on the Internet and the World Wide Web!
  358.  
  359. You can get all of the latest MVP shareware releases, find out news
  360. of future activities, and give feedback to MVP on the Internet.  To
  361. visit our home page, just set your WWW browser to this URL:
  362.  
  363.    http://theyellowpages.com/shareware/mvp.htm
  364.  
  365. While there, you can see descriptions of all our releases, download
  366. the shareware versions with a click of your mouse button, and check
  367. out full color screen shots for all of our games.  Be sure to leave
  368. feedback telling us how you like our page!  
  369.  
  370. If you prefer using direct ftp to get our files, you can find them
  371. at the following sites:
  372.  
  373.    ftp.uwp.edu/pub/msdos/games/mvp
  374.    ftp.uml.edu/msdos/games/mvp
  375.    wuarchive.wustl.edu/systems/msdos/msdos-games/mvp
  376.  
  377. These sites also have many mirrors, so just look for a game site
  378. with an MVP directory, and you'll be assured of getting the best
  379. games around!
  380.  
  381. By the way, Harold Gregg & Company graciously donated their time and
  382. resources to set up our WWW page, and we highly recommend them to
  383. anyone interested in setting up a home page.  They can be reached at
  384. http://theyellowpages.com.
  385.  
  386.                       All About the STK 
  387.  
  388. What Is It?  What Does It Do?
  389. -----------------------------
  390. DiamondWare's Sound ToolKit (STK) is a sound library written in 99%
  391. real-mode assembler (except for API "wrapper" functions).  It
  392. supports FM music synthesis and digital audio on Sound Blaster and
  393. compatible hardware.
  394.  
  395. The STK can play up to sixteen digital effects at the same time
  396. (called polyphony).  Unlike other sound libraries, there are no
  397. restrictions on calling INT 21h (DOS) functions.
  398.  
  399. It's linkable with any C/C++, Pascal, or BASIC program, which means
  400. adding the STK to a mostly-completed program will be easy.
  401.  
  402. The STK is built tough.  DiamondWare has acquired over thirty sound
  403. boards, fifty books (including manufacturer's specifications), four
  404. operating systems, and five brands of CPUs to test the STK during
  405. development.  All this testing means that programmers who use the
  406. STK won't field millions of tech-support calls saying "the sound
  407. doesn't work," or "it doesn't crash unless I enable the sound
  408. option."
  409.  
  410. The STK's autodetect is powerful.  It can determine the hardware
  411. type, port, DMA channel, and IRQ level automatically--under every
  412. major DOS environment (including Windows DOS boxes, OS/2 DOS boxes,
  413. Novell DOS, QEMM, 386MAX, and EMM386), running on every major brand
  414. of CPU, including Intel, AMD, Cyrix, IBM, and Texas Instruments.
  415. The STK goes directly to the sound hardware, requiring neither
  416. environment variables nor user input.  And, should you wish, you can
  417. override any setting.
  418.  
  419. The STK provides "mixer" functionality.  The better boards (Sound
  420. Blaster Pro and up) have chips on-board which can control the volume
  421. level of music and sound effects independently, and also the total
  422. volume.  For sound boards that don't have such a chip, the STK can
  423. mix levels in software.
  424.  
  425. DiamondWare's STK supports an important subset of the MIDI
  426. specification, including true dynamic patch changes, velocity
  427. sensitivity, pitch bend, and aftertouch.  Future versions of the STK
  428. will support more of the MIDI specification.
  429.  
  430. The STK doesn't allocate any memory dynamically.  It doesn't make
  431. any INT 21h calls (except during autodetect and initialization).  It
  432. doesn't require any outside code to link.  It doesn't have to
  433. reprogram the timer hardware, though it comes with optional code to
  434. do this.  The STK doesn't take hundreds of kilobytes of RAM.  It
  435. doesn't pollute your users' install directories with scores of
  436. files.  And it doesn't use a single line of code from a sound board
  437. manufacturer, or any other library vendor.
  438.  
  439. What Are Its Limitations?
  440. -------------------------
  441. The STK is a kit for Sound Blasters, SB-compatibles, and SB-clones.
  442. It will not work with the native modes of non-Creative Labs' sound
  443.  
  444. boards.  [Creative Labs is the major player in the sound board
  445. market.]  However, it has been designed and tested to work with their
  446. compatible modes, (which are often only 90-95% "compatible").
  447.  
  448. It requires a 386SX or higher processor .  This is not because it
  449. uses so much computing power (it doesn't), but because we've made
  450. extensive use of instructions and registers which are unavailable on
  451. the 286 and lower.
  452.  
  453. The STK can't play VOC files (sound effects) greater than 64k,
  454. although it supports easy sequencing of split-up VOC files.
  455.  
  456. The STK needs interrupts to remain active.  Disabling interrupts for
  457. extended periods of time will pause all sound playback, until
  458. interrupts are enabled again.  Music notes will hang, and digitized
  459. will skip and repeat like a CD player trying to track a bad disc.
  460.  
  461. The STK does not support sampling rates under 4 KHz or over 24 KHz.
  462.  
  463. The STK does not manage resource files, nor play files from disk.
  464. You must manage your directory structure, and load each file into a
  465. buffer before the STK can play it.
  466.  
  467. The STK can't change its settings (like volume levels) "in the
  468. background".  If you want to do this, then write some code that
  469. checks the current time, and slowly change the volume level.  It's
  470. no harder than moving 20 space aliens plus 1 player and 5 bullets.
  471.  
  472.                        Before You Start
  473.  
  474. Prerequisite Knowledge
  475. ----------------------
  476. DiamondWare's STK is a programmer's library, not a game.  As such,
  477. it's a highly technical product.  While this document was written to
  478. tell you all about the STK, it can't tell you how to program.
  479. Before reading this document, you should be familiar with PC
  480. programming -- including bitwise operations and linking with external
  481. libraries.
  482.  
  483. Prior PC programming experience in a language linkable with the STK,
  484. including knowledge of bit-level operations, is presumed.
  485.  
  486. The STK was designed to work with C/C++, Pascal, and BASIC.  Even if
  487. you will not be programming in C, several conventions and examples
  488. in this manual are given only in C, so prior C experience will be
  489. helpful.  For example, all function prototypes are given for C,
  490. Pascal, and BASIC; but in general, descriptions are given only using
  491. C terminology.  Here is a guide for Pascal and BASIC users to aid in
  492. understanding C:
  493.  
  494. All subroutines are called "functions", although in Pascal and BASIC
  495. they may be "functions", "procedures", or "subroutines".  A C
  496. struct, often called a structure, is the equivalent of a Pascal
  497. record and a BASIC TYPE.
  498.  
  499. C expresses bitwise OR as a pipe |, bitwise AND as an ampersand &,
  500. logical OR as two pipes ||, and logical AND as two ampersands &&.  C
  501. comments are either a double slash //Comment which is a comment
  502.  
  503. until the end of the line (equivalent to BASIC's apostrophe or REM)
  504. or /*Comment*/ (equivalent to Pascal's (*Comment*)).  BASIC
  505. programmers should ignore all underscores _.
  506.  
  507. There's one other important thing for Pascal and BASIC programmers
  508. to know about C. The ampersand & operator can also be used to take
  509. the address of a variable.  For example:
  510.  
  511.                 dws_MSongStatus(&mstat);
  512.  
  513. This call passes the address of the variable mstat to the function
  514. (which puts the song's status into the variable).  This is
  515. equivalent to Pascal's var or BASIC's SEG (pass by reference)
  516. calling conventions.
  517.  
  518. In specific instances, Pascal and BASIC differences with C will be
  519. explicitly listed.
  520.  
  521. Sometimes in this document, Turbo Pascal is distinguished from other
  522. languages.  This is because Pascal works with "units."  A unit
  523. contains not only the linkable program code, but also the
  524. declarations which tell the compiler about that program code and the
  525. data types it requires.  C and BASIC use a different model, in which
  526. the compiler is told to include some human-readable header file,
  527. which contains declarations of code and data types, but no more.
  528. The compiler produces a .OBJ file, which the linker puts together
  529. with other .OBJ files (and .LIB files, which are really just several
  530. .OBJ files in one) to make the final .EXE.
  531.  
  532. The Sound ToolKit is distributed with a single .LIB which works with
  533. all Microsoft languages, Borland C/C++, and Turbo Assembler.  Header
  534. files are provided for C/C++ and BASIC.  Also included are unit
  535. files for Turbo Pascal versions 6 and 7.
  536.  
  537. All human-readable source files provided on disk were produced with
  538. tab stops set to 2.
  539.  
  540.                        Installing the STK
  541.  
  542. The STK is distributed on a single disk containing two files:
  543. INSTALL.COM and STK.EXE.  To install the STK simply insert the
  544. distribution disk into drive A or B, and type A: or B:, and press
  545. ENTER.  Then type INSTALL, and press ENTER.  The installation
  546. program will create a directory and install the files to it.
  547.  
  548. That's it; it's installed.  If you have downloaded it, simply unzip
  549. the zip file (using Pkunzip 2.04 or higher) into a directory on your
  550. hard drive.
  551.  
  552. Make sure you put the header files and the library file (or the
  553. Pascal unit file) where the compiler and linker can find them.  If
  554. you need more information on this and related topics, your
  555. compiler's manual will be far more detailed than is possible here,
  556. and will cover your specific software environment.
  557.  
  558. You may want to put the executables (MID2DWM.EXE, VOC2DWD.EXE, etc.)
  559. in an existing binaries directory, or set the PATH environment
  560.  
  561. variable to point to them.  Your MS-DOS manual describes this in
  562. detail.
  563.  
  564.                     Linking With the STK
  565.  
  566. The STK has been designed so that calling it in a real-world program
  567. is relatively simple.  However, the STK is a non-trivial component
  568. of your program, and there are some non-obvious things to know.
  569.  
  570. As mentioned above, the STK works with C/C++, Pascal, and BASIC.
  571. Additionally, it should work with any other linkable language which
  572. supports the Intel/Microsoft .OBJ file format specification (such as
  573. assembler).  If you are using such a language, you will have to port
  574. the C header files to your language.  Link with DWS.LIB as you would
  575. with any other library.
  576.  
  577. By far, the easiest way to use the STK is in large model programs.
  578. In a large model program, all function calls and all data references
  579. are made via 32-bit segment:offset addresses.  The STK expects this
  580. convention.
  581.  
  582. It's possible to use the STK in mixed model programs, where some
  583. code or data is "near" and other code or data is "far."  As long as
  584. the STK's code and data is all "far," this can work.  See your
  585. compiler manual for details on how to do this.
  586.  
  587.                     About Music and Sound
  588.  
  589. Introduction
  590. ------------
  591. Sound, especially in the PC world, is a complicated topic.  This
  592. section will serve as an overview of the subject.  The STK provides
  593. functionality for the two primary aspects of sound programming: FM
  594. synthesis for playback of MIDI (.MID format) music, and digital
  595. audio for playback of digitally sampled (.VOC format) sound effects.
  596.  
  597. FM Synthesis
  598. ------------
  599. FM stands for "Frequency Modulation," which refers to how musical
  600. notes are created.  In FM, a sound is created from two operators,
  601. which are simple sine waves.  One operator, called the modulator, is
  602. used to modify the frequency output by the other, called the
  603. carrier.  The resulting waveform is surprisingly rich (much more so
  604. than Amplitude Modulation).  FM synthesis is a convenient method for
  605. playing music.
  606.  
  607. The waveform is put through an envelope, which alters the output
  608. volume during the four distinct phases of a musical note: attack,
  609. sustain, release, and decay.
  610.  
  611. On Sound Blasters, FM synthesis is performed by a Yamaha OPL-2 or
  612. OPL-3 chip in the digital domain.  The total output of all voices is
  613. sent to a special Yamaha Digital-to-Analog Converter (DAC), which
  614. creates low-level analog signals.
  615.  
  616. Programmed properly, the FM synthesizer can produce fairly nice
  617. instrument sounds, including surprisingly good drums.  The key
  618.  
  619. phrase here is "fairly nice." If you want to create a mood, you can
  620. do it with FM synthesis.  However, you cannot realistically
  621. reproduce the sound of most acoustic instruments (FM does a better
  622. job with "electronic" sounds).
  623.  
  624. Music is created by a musician, a computer, and sequencer software.
  625. Usually he'll use a (music) keyboard controller to enter note data,
  626. although some musicians may type it in on their computer's keyboard.
  627.  
  628. The result of the musician's toil and effort, the .MID file, is a
  629. collection of note information, but it isn't sufficient to make
  630. music; it contains no information about what the instruments should
  631. sound like.  A patch bank, which is a set of instrument definitions,
  632. fills this gap.  This nomenclature comes from the old days when
  633. technicians plugged patch cords into racks of equipment to change
  634. synthesizer sounds.  Today, patch is a synonym for a single musical
  635. instrument sound.
  636.  
  637. The OPL FM chip uses eleven parameters to describe an instrument.  A
  638. single instrument patch is therefore 11 bytes (plus a header and
  639. some waste).  Software such as Symphonix OPL Patch Editor/Librarian
  640. by Flashpoint Productions (included with the registered version of
  641. the STK) is the best way to tinker with patches.
  642.  
  643. Collections of patches are stored in instrument bank files (.IBK
  644. format).  Although you can put any instrument at any index in the
  645. file, you're going to discover that only songs custom-written for
  646. that instrument bank file will play correctly.  Other songs will
  647. probably sound totally unacceptable.
  648.  
  649. Enter the General MIDI standard, which specifies all 128 patches
  650. (e.g. instrument 1 is Grand Piano).  Although, for FM synthesis,
  651. General MIDI compliance is not required, we strongly recommend it.
  652. When the industry moves to wavetable boards, your music will sound
  653. good on most boards.  (Eventually, all sound hardware will support
  654. General MIDI and wavetable.  But today's installed base is about 99%
  655. FM and 1% wavetable.  Sales of FM hardware are still much higher
  656. than wavetable.  Wavetable sales are projected to surpass FM sales
  657. in 1996.  Wavetable installations will surpass FM no earlier than
  658. 1997.  Considering this, and the fact that many wavetable boards
  659. also include or emulate FM, we believe FM is far more important than
  660. wavetable right now.  Good FM is currently a big market advantage.)
  661.  
  662. Digital Audio
  663. -------------
  664. In digital audio, an analog waveform is translated into the digital
  665. domain by sampling (i.e. measuring) the amplitude of the wave at
  666. regular intervals.  The sampling rate is the frequency at which this
  667. is done.
  668.  
  669. As Nyquist proved, the sampling rate must be at least twice as high
  670. as the highest frequency in the waveform being sampled, or else
  671. aliasing occurs.  When this happens, the sound takes on an
  672. unpleasant metallic overtone.
  673.  
  674. Let's say you're recording the sound of glass breaking, which
  675.  
  676. includes some very high frequencies -- we'll assume up to about 11
  677. KHz.  Unless you're using a low-pass analog filter (the Sound
  678. Blasters have several) to cut out high frequencies, you should
  679. sample at 22 KHz or higher.
  680.  
  681. Note: sampling at very low rates will have undesirable side-effects.
  682. Speech will be lisped, and in general, everything will sound dull.
  683.  
  684. Dynamic range, which is the difference between the softest and
  685. loudest sounds, is also important.  16-bit samples sound better than
  686. 8-bit samples because the extra byte allows more precision, and more
  687. contrast between soft and loud.
  688.  
  689. It is important to record your sound effects at a low volume, if you
  690. plan on playing more than one or two simultaneously.  You can also
  691. compress the dynamic range when you prepare the sound.  This will
  692. help you avoid clipping (i.e. exceeding the dynamic range of the
  693. playback hardware).
  694.  
  695.                        General Guidelines
  696.  
  697. Don't Touch That Compiler Yet!
  698. ------------------------------
  699. Before you can bring sound into your program, you must convert the
  700. .MID and .VOC files into formats that are quickly and easily parsed
  701. at run-time.  Use MID2DWM and VOC2DWD, respectively.  See the
  702. Utilities heading in the Reference section for more information on
  703. how to use these programs.
  704.  
  705. The Autodetect
  706. --------------
  707. Before you can initialize the STK, you must know the sound hardware
  708. settings: base port, DMA channel, and IRQ level.  You can ask the
  709. user, you can parse the BLASTER environment variable, or you can use
  710. the STK's autodetect.  The last is the recommended method.
  711.  
  712. Using the autodetect is easy.  Create two structs, one of type
  713. dws_DETECTOVERRIDES, and the other of type dws_DETECTRESULTS.  Set
  714. the baseport, digdma, and digirq fields of the overrides struct to
  715. 65535 (to autodetect them), or initialize them with their correct
  716. values.  Either way, call dws_DetectHardware, passing the address of
  717. both structs as parameters.  The results struct will be filled in.
  718.  
  719. Note: you must call dws_DetectHardware even if you know these values
  720. in advance.  The reason is that it stores information in the
  721. reserved field.
  722.  
  723. Note: If you write the settings to a disk file (not recommended),
  724. make sure you write the entire struct.  dws_Init requires the
  725. information in the reserved field and may crash if it's not there.
  726.  
  727. For more information about these and other structures, see Data
  728. Structures in the Reference section.
  729.  
  730. Many sound boards require the user to load drivers from either
  731. CONFIG.SYS or AUTOEXEC.BAT (e.g. the Advanced Gravis Ultrasound and
  732. SBOS) These drivers must be loaded before any STK-enabled software
  733.  
  734. is run.  If the driver isn't loaded, some boards may not respond, or
  735. worse yet, could take on default values which conflict with other
  736. hardware.  This last case is a major potential problem and could
  737. cause a crash.
  738.  
  739. In the overwhelming majority of cases, the autodetect will quietly
  740. do its job.  It is robust, and there are only two known (obscure)
  741. failure cases.  If you find any others, please report them to
  742. DiamondWare!
  743.  
  744. The first failure case occurs only when the STK is running in a
  745. Microsoft Windows Enhanced-mode DOS box.  If the user has another
  746. card which is constantly doing DMA on an 8-bit channel, the STK will
  747. crash the machine.  The only card known to do this is the NE2100 bus
  748. mastering ethernet adapter, which uses a 16-bit DMA channel 99% of
  749. the time.  (It's an expensive, high-performance card; running it on
  750. an 8-bit DMA channel is like putting 85-octane gas into a sports
  751. car.)  Other devices that use DMA, like CD-ROM and SCSI controllers,
  752. do not perform DMA transfers unless they are in use, and will not
  753. cause any problems with the STK.
  754.  
  755. The second failure case occurs only with Aria 16 and Aria 16se
  756. cards.  If the Sound Blaster portion of the board is configured for
  757. IRQ 2/9, the autodetect will incorrectly return the IRQ used by the
  758. MIDI portion of the board, rather than that of the digitized
  759. portion.
  760.  
  761. Initializing the STK
  762. --------------------
  763. After calling dws_DetectHardware, you'll need a struct of type
  764. dws_IDEAL.  Its fields are requests for STK services.  Set each to
  765. the desired values.  Then call dws_Init, passing the address of the
  766. dws_DETECTRESULTS and dws_IDEAL structs as parameters.
  767.  
  768. This struct is here for three reasons.  The first is to tell the STK
  769. the initial sampling rate you want.  The second reason is to
  770. conserve CPU cycles.  The STK will run faster with fewer digital
  771. voices.  The last reason is that future versions of the STK will
  772. offer more features (e.g. 16-bit, stereo, etc.)  You may not want
  773. some or all of these services.  Initialize this struct properly, and
  774. you will easily incorporate STK upgrades into your programs.
  775.  
  776. When the STK initializes, it resets the sound hardware to a 100%
  777. known state, including setting the mixer to maximum volume.  It also
  778. sets up its own internal data structures, Interrupt Service Routines
  779. (ISRs), etc.  Few STK functions will work until you call dws_Init.
  780.  
  781. The Hardware Timer
  782. ------------------
  783. Next, initialize the hardware timer.  The STK must be called at a
  784. relatively high rate.  The DiamondWare Timer (DWT) module will do
  785. the trick, or you can use your own code.
  786.  
  787. If you're going to use the DWT, call dwt_Init, passing it a rate
  788. constant as a parameter.  The DWT will do all timing functions
  789. necessary to the STK (and keep time for your game, too).  See
  790. dwt_Init in the Function Reference for complete information.
  791.  
  792. If you have your own code, initialize it now.  Make sure it will
  793. call dws_Update once during each hardware timer interrupt.  The DWT
  794. will not interfere, or even link into your application.
  795.  
  796. Initiating Playback
  797. -------------------
  798. To play a song, first allocate a buffer large enough to hold the
  799. .DWM file, and then read it in.  Create a struct of type dws_MPlay;
  800. set the track field to point to this buffer, and the count field to
  801. the number of times to play.  Now call dws_Mplay.  The song will
  802. play in the background.
  803.  
  804. To play a sound effect, allocate a buffer, and read in the .DWD
  805. file.  Create a struct of type dws_DPlay; set the snd field to point
  806. to the buffer, the count field to the number of times to play,
  807. ignore priority field (for now), and set the presnd field to 0 (for
  808. now).  Now call dws_DPlay.  The sound will play in the background.
  809.  
  810. For more information on these structs and calls, see the Advanced
  811. Tutorial section, or The Functions heading and The Data Structures
  812. heading in the Reference section.
  813.  
  814. Note to BASIC users: make sure that your buffers don't move around
  815. during "garbage collection".
  816.  
  817. The Rules of the Game
  818. ---------------------
  819. The STK can play one music track, and up to sixteen sound effects
  820. (at the same sampling rate) at the same time.  Once a song or sound
  821. is playing, you can let it play without doing anything else.  You
  822. can even make DOS calls.
  823.  
  824. In the mode used by the STK, the FM chip allows up to 6 musical
  825. instruments and 5 drums to play simultaneously.  Drums can play and
  826. replay, still sounding good, but it's important that your music
  827. sound (and/or sustain) no more than 6 melody notes at a time.  The
  828. STK player will automatically drop notes out (though it won't
  829. crash), but a musician would inevitably make a better decision as to
  830. which notes are important than any computer algorithm.
  831.  
  832. There are five drums built in to the STK, chosen as a reasonable
  833. compromise: bass drum, snare, high hat, tom tom, and top cymbal.
  834. All other drums are mapped to these five.
  835.  
  836. The STK will refuse to exceed the dynamic range of the hardware it's
  837. playing on.  This means that if you try to play 4 sound effects
  838. which all use the full 8 bits of dynamic range, you'll only hear the
  839. one with the highest priority.  Until it ends, the others will not
  840. be played, although they will continue to advance silently.  If the
  841. sound with the highest priority ends, any remaining sounds are added
  842. back in, to the limit of the dynamic range of the playback hardware.
  843.  
  844. Playback Status
  845. ---------------
  846. The functions dws_MSongStatus and dws_DSoundStatus determine whether
  847. a song or sound is playing or finished.  Each of these functions
  848. requires you to create a status variable for them to use.  To get
  849.  
  850. the status of your music, pass the address of the status variable to
  851. dws_MSongStatus.  To query the status of a specific sound effect,
  852. pass the address of the status variable, as well as its ID (from the
  853. soundnum field of its dws_DPLAY structure) to dws_DSoundStatus.
  854.  
  855. Each bit of the status variable is a flag.  Perform a bitwise and
  856. between the status variable and the playback condition you would
  857. like to test.  For example, dws_MSONGSTATUSPLAYING & status
  858. evaluates to a 1 if the music is still playing, and
  859. dws_DSOUNDSTATUSPLAYING & status evaluates to a 1 if the sound
  860. effect is still playing.  For a complete list of conditions, refer
  861. to both routines in the The Functions heading in the Reference
  862. section.
  863.  
  864. Keeping Time
  865. ------------
  866. The DWT provides a double-word (32 bit, unsigned) timer, which
  867. begins at 0 when DWT is initialized, and increments once per timer
  868. interrupt.  Calling dwt_MasterTick returns the number of clock ticks
  869. since time began (i.e.  when you called dwt_Init).  dwt_Pause and
  870. dwt_UnPause suspend and restart the master clock, respectively.
  871. They don't affect either music or digitized sound playback.
  872.  
  873. Tracking Errors
  874. ---------------
  875. Most functions in the STK return a word (16-bit, unsigned) value.
  876. This is a boolean value, indicating the success/failure of the
  877. function.  True (1) is success, and false (0) means that an error
  878. has occured.  In the case of an error, call dws_ErrNo to determine
  879. what happened.
  880.  
  881. dws_ErrNo behaves much like the errno variable in the C standard
  882. library.  Initially it's 0, and it's only changed when a function
  883. encounters an error.  It's important to check it after each call
  884. which fails, or else you won't know which one generated the error.
  885. Under The Functions, in the Reference section, there is a list of
  886. errors for each function.  You may assume this list is exhaustive;
  887. if an error isn't listed for a given function, then that function
  888. cannot generate that error.
  889.  
  890. Stopping Playback
  891. -----------------
  892. Call dws_MPause or dws_MUnPause to suspend or restart music
  893. playback.  Call dws_MClear to stop the current song.  Make sure you
  894. stop music playback before you deallocate the song buffer, or you
  895. may get some noise.
  896.  
  897. Call dws_DPause or dws_DUnPause to suspend or restart all digitized
  898. sound playback.  Call dws_DClear to stop all currently-playing
  899. sounds.  Call dws_DDiscard to stop a particular sound from playing;
  900. this function requires the sound's ID as a parameter (from the
  901. soundnum field of its dws_DPLAY structure).  Call dws_DDiscardAO to
  902. stop all occurrences of a digitized sound; this function requires a
  903. pointer to the sound's buffer.
  904.  
  905. Shutting Down
  906. -------------
  907. Before exiting to DOS, you must clean up.  First, call dwt_Kill (or
  908. shut down your own timer module).  Next, call dws_Kill.  Finally,
  909. deallocate any buffers you may have allocated during execution.
  910.  
  911. There is a problem in Microsoft Windows Enhanced-mode DOS boxes when
  912. the sound board is set to IRQ 2/9, and Windows isn't configured for
  913. the sound board.  The first time an STK-using program runs in this
  914. environment, it will work perfectly.  But if the user exits the
  915. STK-using program, and restarts it before restarting Windows, there
  916. will be no digitized sound (FM music will play normally).
  917.  
  918.                           Tutorial 
  919.  
  920. This tutorial will walk you through MINAPP.C, an application
  921. framework which fulfills the minimum requirements for implementing
  922. the STK in a program.  It is intended for learning the basics; it
  923. does not check for STK errors at all.  The source code for the
  924. sample applications PLAYDWD, PLAYDWM, and FINDSB are provided in C,
  925. Pascal, and BASIC on disk.  They include (more) robust
  926. error-checking, and are highly commented.  Please review them as
  927. well.
  928.  
  929. Setting Up:  Includes and Variables
  930. -----------------------------------
  931. #include <<stdio.h>>
  932. #include <<malloc.h>>
  933. #include "dws.h"
  934. #include "dwt.h"
  935.  
  936. void main (void)
  937. {
  938.     FILE *fp;
  939.     byte __far *sound, *song;
  940.     word mstatus, dstatus, msize, dsize;
  941.     dws_DETECTOVERRIDES dov;
  942.     dws_DETECTRESULTS   dres;
  943.     dws_IDEAL ideal;
  944.     dws_MPLAY mplay;
  945.     dws_DPLAY dplay;
  946.  
  947. The standard C header file stdio.h is included for the file I/O
  948. functions, and malloc.h to support dynamic memory allocation.  dws.h
  949. contains all the STK prototypes, #defines, structures, and type
  950. definitions.  dwt.h provides the same, for the DWT.
  951.  
  952. MINAPP loads one sound effect, and one piece of music.  sound, a
  953. pointer, holds the address of the sound effect buffer; song, another
  954. pointer, holds the address of the music buffer.  dplay, a struct,
  955. holds all information needed to play the sound effect; mplay,
  956. another struct, holds information for playing the song.  dov, dres,
  957. and ideal are structs required for initialization.
  958.  
  959. Loading Songs and Sounds
  960. ------------------------
  961. /* ALLOCATE MEMORY FOR SOUND FILE AND LOAD IT */
  962.     fp = fopen("minapp.dwd", "rb");
  963.     fseek (fp, 0L, SEEK_END);
  964.     sound = _fmalloc (dsize=ftell (fp));
  965.     fseek (fp, 0L, SEEK_SET);
  966.     fread (sound, dsize, 1, fp);
  967.     fclose (fp);
  968.  
  969. /* ALLOCATE MEMORY FOR SONG FILE AND LOAD IT */
  970.     fp = fopen("minapp.dwm", "rb");
  971.     fseek (fp, 0L, SEEK_END);
  972.     song = _fmalloc (msize=ftell (fp));
  973.     fseek (fp, 0L, SEEK_SET);
  974.     fread (song, msize, 1, fp);
  975.     fclose (fp);
  976.  
  977. These two sections allocate buffers to store the music and the
  978. sound, then read the files into them.  minapp.dwm began life as
  979. minapp.MID and gm.ibk, and was converted by MID2DWM.  minapp.dwd
  980. began as MINAPP.VOC, and was converted by VOC2DWD.
  981.  
  982. Initializing the STK
  983. --------------------
  984. /* AUTODETECT SOUND CARD */
  985.     dov.baseport = 65535;
  986.     dov.digdma   = 65535;
  987.     dov.digirq   = 65535;
  988.     dws_DetectHardWare (&dov, &dres);
  989.  
  990. /* INITIALIZE DIAMONDWARE STK SYSTEM */
  991.     ideal.musictyp   = 1;
  992.     ideal.digtyp     = 8;
  993.     ideal.digrate    = 10989;
  994.     ideal.dignvoices = 16;
  995.     ideal.dignchan   = 1;
  996.     dws_Init (&dres, &ideal);
  997.  
  998. Notice how all fields in the struct, dov, are set to 65535.  This
  999. tells dws_DetectHardWare to autodetect the corresponding sound
  1000. hardware parameters.  The results of this are returned in the dres
  1001. struct.  We initialized the ideal struct to request the desired STK
  1002. services (in this case overkill, since we only need one digitized
  1003. voice).  When we call dws_Init, the sound hardware and the STK are
  1004. set up for business.
  1005.  
  1006. Optional Timer Module
  1007. ---------------------
  1008. /* INITIALIZE OPTIONAL TIMER MODULE */
  1009.     dwt_Init (dwt_72_8HZ);
  1010.  
  1011. A PC bootstraps (starts up) with a rate of 18.2 clock ticks per
  1012. second, but the STK requires a higher rate.  Just as importantly,
  1013. the STK must be called during each clock tick.  The DiamondWare
  1014. Timer module will do this.  We recommend 72.8 Hz, a good compromise
  1015. between music quality and Windows DOS-box compatibility.  (If you
  1016.  
  1017. don't care about Windows DOS boxes, use 145.6 Hz.)
  1018.  
  1019. Preparing Songs and Sounds
  1020. --------------------------
  1021. /* PREPARE SONG FOR PLAYING */
  1022.     mplay.track = song;
  1023.     mplay.count = 1;
  1024.  
  1025. /* PREPARE SOUND FOR PLAYING */
  1026.     dplay.snd      = sound;
  1027.     dplay.count    = 1;
  1028.     dplay.priority = 1000;
  1029.     dplay.presnd   = 0;
  1030.     dws_DGetRateFromDWD (dplay.snd, &ideal.digrate);
  1031.     dws_DSetRate (ideal.digrate);
  1032.  
  1033. The mplay struct is set up so that a call to dws_MPlay will play the
  1034. song once.  The dplay struct is also set up.  A priority of 1000 is
  1035. arbitrarily chosen, but since no other sound effects will be playing
  1036. in MINAPP, this field has no practical effect.  The presnd field is
  1037. also unused (set to 0), because this example does not sequence
  1038. digital sounds.  The current playback rate is set to the sampling
  1039. rate at which the sound was recorded.
  1040.  
  1041. Initiating Playback
  1042. -------------------
  1043. /* PLAY SONG AND SOUND ONCE */
  1044.     dws_MPlay (&mplay);
  1045.     dws_DPlay (&dplay);
  1046.  
  1047. A call to dws_MPlay starts the music, and a call to dws_DPlay begins
  1048. playback of the digitized sound effect.
  1049.  
  1050. Wait 'Til the Fat Lady Sings
  1051. ----------------------------
  1052. /* MAIN LOOP */
  1053.     do
  1054.     {
  1055.         dws_DSoundStatus(dplay.soundnum, &dstatus);
  1056.         dws_MSongStatus(&mstatus);
  1057.     }
  1058.     while ((mstatus & dws_MSONGSTATUSPLAYING) ||
  1059.               (dstatus & dws_DSOUNDSTATUSPLAYING));
  1060.  
  1061. We query the song and sound status.  The status is placed in a
  1062. bitfield variable, via its address.  In the case of the music, we're
  1063. interested in the dws_MSONGSTATUSPLAYING field; in the case of the
  1064. digitized sound effect, we're interested in the
  1065. dws_DSOUNDSTATUSPLAYING.  When this field is 1, it means that the
  1066. song or sound, respectively, is playing.
  1067.  
  1068. Shutting Down
  1069. -------------
  1070. /* CLEAR ALL ALLOCATED MEMORY */
  1071.     _ffree (song);
  1072.     _ffree (sound);
  1073.  
  1074. /* DE-INITIALIZE STK */
  1075.     dwt_Kill();
  1076.     dws_Kill();
  1077. }
  1078.  
  1079. The buffers containing the music and sound effect are now
  1080. deallocated.  Normally, dws_DClear and dws_MClear would be called
  1081. before freeing these buffers, but since we know that no sounds are
  1082. playing at the moment, the calls are unnecessary.  The DWT is
  1083. de-initialized first by calling dwt_Kill, then the entire STK engine
  1084. is shut down by calling dws_Kill.  That's it!
  1085.  
  1086.                         Advanced Tutorial 
  1087.  
  1088. Working with the Advanced Features
  1089. ----------------------------------
  1090. The example code fragments below illustrate sequencing and polyphony. We 
  1091. assume that the STK has been initialized.  sfx1 and sfx2 are digital sounds in
  1092. memory.  The following shows how the two dws_DPLAY structures are set up:
  1093.  
  1094.         dplay1.snd      = sfx1;
  1095.         dplay2.snd      = sfx2;
  1096.         dplay1.count    = 1;
  1097.         dplay2.count    = 1;
  1098.         dplay1.priority = 500;
  1099.         dplay2.priority = 1000;
  1100.         dplay1.presnd   = 0;
  1101.         dplay2.presnd   = 0;
  1102.  
  1103. Each sound effect is set to play once, and the second sound is given
  1104. a higher priority than the first.  The presnd field of both structs
  1105. is not set for sequencing.
  1106.  
  1107. Sequencing
  1108. ----------
  1109. The presnd field allows you to sequence sounds to play one after the
  1110. other.  The first sample of the second sound plays after the last
  1111. sample of the first sound.  The effect is that of a single sound,
  1112. playing seamlessly.
  1113.  
  1114. This feature is useful if you want to break a long sound into
  1115. several pieces which can fit into memory.  Or a sound may have
  1116. several different continuations, depending on player input (e.g.  a
  1117. gun fires, continuing with either a scream or a ricochet, depending
  1118. on whether the bullet hits).
  1119.  
  1120. Set the presnd field of a dplay struct to the soundnum of the sound
  1121. you want to sequence after, or use 0 if the sound is stand-alone.
  1122.  
  1123. Note: if you specify a non-zero sound number (which corresponds to a
  1124. sound actually playing), the value returned in soundnum is the same
  1125. as the value specified in presnd.  The new sound will not play
  1126. immediately, but will wait until the first sound is done.
  1127.  
  1128. The priority field is not related to sequencing.
  1129.  
  1130.     dws_DPlay (&dplay1);
  1131.     dplay2.presnd = dplay1.soundnum;
  1132.     dws_DPlay (&dplay2);
  1133.  
  1134. This plays dplay1 followed by dplay2.  If you are sequencing more
  1135. than two sounds, call dws_DSoundStatus to determine when it's safe
  1136. to sequence each sound after the second.
  1137.  
  1138. Polyphony
  1139. ---------
  1140. To play multiple digital sounds, call dws_DPlay more than once.
  1141.  
  1142. The presnd field has no bearing on polyphony.
  1143.  
  1144.     dws_DPlay (&dplay1);
  1145.     dws_DPlay (&dplay2);
  1146.  
  1147. The sounds start simultaneously.  dplay1, the first sound, has a
  1148. priority of 500.  dplay2 has a priority of 1000.
  1149.  
  1150. These numbers are arbitrary; it is the relationship between them
  1151. that counts.  Priorities of 1 and 2 will have the same results.
  1152.  
  1153. Note: if these two sounds together do not exceed the dynamic range
  1154. of the hardware, they'll both play.  However, if the total dynamic
  1155. range used by both sounds exceeds 8 bits, then you will hear only
  1156. the second sound (its priority is higher).  If the second sound is
  1157. shorter, then the first sound will be heard when the second one
  1158. ends.  Until then, it will advance silently.
  1159.  
  1160.                           Reference
  1161.  
  1162. This section of the manual is broken down into several headings: The
  1163. Functions, The Errors, The Data Structures, The Utilities, and The
  1164. File Formats.
  1165.  
  1166.                         The Functions
  1167.  
  1168. Preamble
  1169. --------
  1170. There are two headers provided with the STK.  The first is for the
  1171. sound library (DWS.H for C and DWS.BI for BASIC), and the other for
  1172. the DiamondWare Timer module (DWT.H for C and DWT.BI for BASIC).
  1173.  
  1174. For Turbo Pascal version 6 and 7, there are two .TPU files provided.
  1175. Additionally, although it's not strictly necessary, DWS.PAS (which
  1176. also contains the timer module) is provided so you can see how
  1177. everything is declared.  The sound library header declares the
  1178. constants for each error the STK can generate, some bit field
  1179. constants, the data structures used by the STK, and the prototypes
  1180. of the functions.
  1181.  
  1182. This is a complete list, in alphabetical order, of functions
  1183. provided by the STK and the optional timer module.  Each function
  1184. will be listed with a general description, as well as the
  1185. declaration syntax (prototype) for C, Pascal, and BASIC (in that
  1186. order), parameters, return value, possible error conditions, and
  1187. related functions.
  1188.  
  1189. Most STK functions have a boolean return value to indicate success
  1190. (true), or error (false).  If an error occurs, call dws_ErrNo to
  1191. determine what happened.  Unless otherwise noted, the STK will
  1192. perform no action during any call which returns an error, including
  1193. modifiying structs -- all return values are undefined.
  1194.  
  1195. Most errors are provided to help you integrate the STK into your
  1196. application; once your program is stable, you should not expect to
  1197. see any errors occur.
  1198.  
  1199. All functions and all pointers are far.  All functions use the
  1200. Pascal calling convention.
  1201.  
  1202. The Optional Timer Module
  1203. -------------------------
  1204. If you have written your own hardware timer code which reprograms
  1205. the timer rate, then you don't need the DWT.  Simply don't call our
  1206. module, and it won't link into your application.
  1207.  
  1208. The DWT reprograms the hardware timer to run at a much faster rate
  1209. than normal, while keeping the DOS and BIOS clocks happy by calling
  1210. them at 18.2 Hz (like they expect).  The DWT makes the call to
  1211. dws_Update, which is required to keep the STK happy.  And DWT will
  1212. also keep time in a way useful for video games and multimedia
  1213. applications.  Even if the user has no sound hardware installed, you
  1214. can still use DWT for its timing functions without any ill effect.
  1215.  
  1216. dws_DClear
  1217.  
  1218.     Prototypes
  1219.  
  1220.     word dws_DClear(void);
  1221.     function dws_DClear : word;
  1222.     DECLARE FUNCTION dwsDClear% ALIAS "DWS_DCLEAR" ()
  1223.  
  1224.     Description
  1225.     
  1226.     This function stops all digitized sounds from playing.  Returns
  1227.     success, even if no sounds are currently playing.
  1228.  
  1229.     Parameters
  1230.     
  1231.     None.
  1232.  
  1233.     Return value
  1234.     
  1235.     Boolean success.
  1236.  
  1237.     See also
  1238.     
  1239.     dws_DPause, dws_DDiscard, 
  1240.     dws_DDiscardAO, dws_DPlay
  1241.  
  1242.     Errors
  1243.  
  1244.     dws_NOTINITED, dws_NOTSUPPORTED
  1245.  
  1246. dws_DDiscard
  1247.  
  1248.     Prototypes
  1249.  
  1250.     word dws_DDiscard(word sndnum);
  1251.     function dws_DDiscard(sndnum : word) : word;
  1252.     DECLARE FUNCTION dwsDDiscard% ALIAS
  1253.         "DWS_DDISCARD" (BYVAL sndnum%)
  1254.  
  1255.     Description
  1256.     
  1257.     This function shuts off a single sound instance.
  1258.  
  1259.     If you attempt to discard a sound which is not currently
  1260.     playing, this function will return success.
  1261.  
  1262.     Parameters
  1263.     
  1264.     sndnum is the sound you wish to discard, from the sound's
  1265.     dws_DPlay structure.
  1266.  
  1267.     Return value
  1268.  
  1269.     Boolean success.
  1270.  
  1271.     See also
  1272.  
  1273.     dws_DDiscardAO, dws_DPause, dws_DClear, dws_DPlay
  1274.  
  1275.     Errors
  1276.  
  1277.     dws_NOTINITTED, dws_NOTSUPPORTED
  1278.  
  1279. dws_DDiscardAO
  1280.  
  1281.     Prototypes
  1282.  
  1283.     word dws_DDiscardAO(byte *snd);
  1284.     function dws_DDiscardAO(snd : dws_BTPTR) : word;
  1285.     DECLARE FUNCTION dwsDDiscardAO% ALIAS
  1286.         "DWS_DDISCARDAO" (BYVAL snd&)
  1287.  
  1288.     Description
  1289.     
  1290.     This function discards all occurrences of one sound effect (.DWD
  1291.     file) that is currently playing.  If you are playing the same
  1292.     sound effect several times, this is an easy way to stop them
  1293.     all -- useful before you deallocate the sound's memory buffer,
  1294.     for example.
  1295.  
  1296.     This function requires that you specify the sound by the address
  1297.     of its buffer in memory.
  1298.  
  1299.     Note: if any sound killed by this function has a sequenced sound
  1300.     waiting to play after it, the sequenced sound will be killed
  1301.     also.
  1302.  
  1303.     Parameters
  1304.     
  1305.     snd is a pointer to the buffer storing the .DWD sound effect.
  1306.  
  1307.     Return value
  1308.  
  1309.     Boolean success.
  1310.  
  1311.     See also
  1312.  
  1313.     dws_DDiscard, dws_DPause, dws_DClear, dws_DPlay
  1314.  
  1315.     Errors
  1316.  
  1317.     dws_NOTINITTED, dws_NOTSUPPORTED, dws_D_NOTADWD,
  1318.     dws_D_NOTSUPPORTEDVER, dws_D_INTERNALERROR
  1319.  
  1320. dws_DetectHardware
  1321.  
  1322.     Prototypes
  1323.  
  1324.     word dws_DetectHardware(dws_DETECTOVERRIDES *dov,
  1325.     dws_DETECTRESULTS *dr); function dws_DetectHardWare(dov :
  1326.     dws_DOPTR; dr :dws_DRPTR) : word; DECLARE FUNCTION
  1327.     dwsDetectHardWare% ALIAS "DWS_DETECTHARDWARE" (SEG dov AS
  1328.         dwsDETECTOVERRIDES, SEG dr AS dwsDETECTRESULTS)
  1329.  
  1330.     Description
  1331.  
  1332.     This is the STK's hardware autodetect.  It detects card
  1333.     settings, or verifies settings you put in dov.  Upon return, dr
  1334.     will be filled with the autodetection results.  DiamondWare
  1335.     recommends calling this function at the beginning of your
  1336.     program, each time it is run, so that if the user changes
  1337.     hardware settings between runs, your program will still work.
  1338.  
  1339.     Parameters
  1340.  
  1341.     dov is a pointer to a dws_DETECTOVERRIDES struct.  Set every
  1342.     field with either a 65535 (to autodetect), or an override (user
  1343.     setting).  User setting values will be accepted on faith (sort of).
  1344.  
  1345.     dr is a pointer to a dws_DETECTRESULTS structure, where the
  1346.     function will return its results.
  1347.  
  1348.     The reserved array in this struct holds important information;
  1349.     if you write the contents of the struct out to a file, write the
  1350.     entire struct!  dws_Init requires all of this information;
  1351.     without it, the STK could crash the computer.
  1352.  
  1353.     The bitfield capability indicates supported features:  
  1354.  
  1355.     0                                       //no sound hardware
  1356.     dws_capability_FM                       //music
  1357.     dws_capability_DIG                      //digitized sounds
  1358.     dws_capability_FM | dws_capability_DIG  //Both
  1359.  
  1360.     Return value
  1361.  
  1362.     Boolean success.
  1363.  
  1364.     See also
  1365.  
  1366.     dws_Init, dws_Kill
  1367.  
  1368.     Errors
  1369.  
  1370.     dws_ALREADYINITTED, dws_DetectHardware_UNSTABLESYSTEM, 
  1371.     dws_DetectHardware_BADBASEPORT, dws_DetectHardware_BADDMA, 
  1372.     dws_DetectHardware_BADIRQ
  1373.  
  1374.     If the machine becomes unstable more than twice, please contact
  1375. DiamondWare!
  1376.  
  1377. dws_DGetRate
  1378.  
  1379.     Prototypes
  1380.  
  1381.     word dws_DGetRate(word *result);
  1382.     function dws_DGetRate(result : dws_WDPTR) : word;
  1383.     DECLARE FUNCTION dwsDGetRate% ALIAS
  1384.         "DWS_DGETRATE" (SEG result%)
  1385.  
  1386.     Description
  1387.  
  1388.     This function returns the sampling rate to which the hardware is
  1389.     currently set.
  1390.  
  1391.     Parameters
  1392.  
  1393.     result is a pointer to the variable that will store the current
  1394.     sampling rate.
  1395.  
  1396.     Return value
  1397.  
  1398.     Boolean success.
  1399.  
  1400.     See also
  1401.  
  1402.     dws_DGetRateFromDWD, dws_DSetRate
  1403.  
  1404.     Errors
  1405.  
  1406.     dws_NOTINITTED, dws_NOTSUPPORTED
  1407.  
  1408. dws_DGetRateFromDWD
  1409.  
  1410.     Prototypes
  1411.  
  1412.     word dws_DGetRateFromDWD(byte *snd, word *result);
  1413.     dws_DGetRateFromDWD(snd : dws_BTPTR; result : dws_WDPTR) : word;
  1414.     DECLARE FUNCTION dwsDGetRateFromDWD% ALIAS "DWS_DGETRATEFROMDWD" 
  1415.         (BYVAL snd&, SEG result%)
  1416.  
  1417.     Description
  1418.  
  1419.     This function returns the sampling rate at which a .DWD file was
  1420.     recorded.
  1421.  
  1422.     Note: this function will work before dws_Init is called.
  1423.  
  1424.     Parameters
  1425.     
  1426.     snd is a pointer to a buffer containing a .DWD file.
  1427.  
  1428.     result is a pointer to a variable that will store the recorded
  1429.     sampling rate.
  1430.  
  1431.     Return value
  1432.  
  1433.     Boolean success.
  1434.  
  1435.     See also
  1436.  
  1437.     dws_DGetRate, dws_DSetRate
  1438.  
  1439.     Errors
  1440.  
  1441.     dws_D_NOTADWD, dws_D_NOTSUPPORTEDVER
  1442.  
  1443. dws_DPause
  1444.  
  1445.     Prototypes
  1446.  
  1447.     word dws_DPause(void);
  1448.     function dws_DPause : word;
  1449.     DECLARE FUNCTION dwsDPause% ALIAS "DWS_DPAUSE" ()
  1450.  
  1451.     Description
  1452.  
  1453.     This function pauses all digitized sound playback.
  1454.  
  1455.     Note: all calls after the first will have no effect until
  1456.     dws_DUnPause is called.  The STK does not maintain a "pause
  1457.     count".
  1458.  
  1459.     Parameters
  1460.  
  1461.     None.
  1462.  
  1463.     Return value
  1464.     
  1465.     Boolean success.
  1466.  
  1467.     See also
  1468.  
  1469.     dws_DUnPause, dws_Discard, dws_DiscardAO, dws_DClear
  1470.  
  1471.     Errors
  1472.  
  1473.     dws_NOTINITED, dws_NOTSUPPORTED
  1474.  
  1475. dws_DPlay
  1476.  
  1477.     Prototypes
  1478.  
  1479.     word dws_DPlay(dws_DPLAY *dplay);
  1480.     function dws_DPlay(dplay : dws_DPPTR) : word;
  1481.     DECLARE FUNCTION dwsDPlay% ALIAS "DWS_DPLAY"(SEG
  1482.         dplay AS dwsDPLAY)
  1483.  
  1484.     Description
  1485.     
  1486.     This function plays a digitized sound.
  1487.  
  1488.     Parameters
  1489.     
  1490.     dplay is a pointer to a filled dws_DPLAY struct, which contains:
  1491.  
  1492.         snd      pointer to a buffer with a .DWD
  1493.         count    number of times to play; 0 means repeat indefinitely
  1494.         priority relative to other sounds; low priority snds may drop
  1495.         soundnum unique ID -- returned by the STK
  1496.         presnd   ID of sound to sequence after; 0 means don't seq
  1497.  
  1498.     Return value
  1499.  
  1500.     Boolean success.
  1501.  
  1502.     See also
  1503.  
  1504.     dws_DDiscard, dws_DDiscardAO, dws_DClear, dws_DSoundStatus
  1505.  
  1506.     Errors
  1507.  
  1508.     dws_NOTINITTED, dws_NOTSUPPORTED, dws_D_NOTADWD,
  1509.     dws_D_NOTSUPPORTEDVER, dws_D_INTERNALERROR,
  1510.     dws_DPlay_NOSPACEFORSOUND
  1511.  
  1512. dws_DSetRate
  1513.  
  1514.     Prototypes
  1515.  
  1516.     word dws_DSetRate(word frequency);
  1517.     function dws_DSetRate(frequency : word) : word;
  1518.     DECLARE FUNCTION dwsDSetRate% ALIAS
  1519.         "DWS_DSETRATE" (BYVAL frequency%)
  1520.  
  1521.     Description
  1522.  
  1523.     This function sets the digitized sampling rate.  If sounds are
  1524.     currently playing, this might sound weird.
  1525.  
  1526.     Note: some sound boards don't support every rate allowed by the
  1527.     Sound Blasters.  Many sound boards will produce an audible click
  1528.     when the rate is changed on the fly.
  1529.  
  1530.     The STK supports sampling rates from 4 KHz to 24 KHz.
  1531.  
  1532.     Parameters
  1533.  
  1534.     frequency is the new sampling rate to use.
  1535.  
  1536.     Return value
  1537.  
  1538.     Boolean success.
  1539.  
  1540.     See also
  1541.  
  1542.     dws_DGetRate, dws_DGetRateFromDWD
  1543.  
  1544.     Errors
  1545.  
  1546.     dws_NOTINITTED, dws_NOTSUPPORTED, dws_DSetRate_FREQTOLOW, 
  1547.     dws_DSetRate_FREQTOHIGH
  1548.  
  1549. dws_DSoundStatus
  1550.  
  1551.     Prototypes
  1552.  
  1553.     word dws_DSoundStatus(word sndnum, word *result); function
  1554.     dws_DSoundStatus(sndnum : word; result : dws_WDPTR) : word;
  1555.     DECLARE FUNCTION dwsDSoundStatus% ALIAS "DWS_DSOUNDSTATUS"(BYVAL
  1556.         sndnum%, SEG result%)
  1557.  
  1558.     Description
  1559.  
  1560.     Internally, the STK stores each sound in a slot.  Each slot can
  1561.     hold up to two sounds -- an active sound and a sequenced sound
  1562.     (which becomes active when the currently active sound ends).
  1563.     The slot is identified by the ID of the sound playing in it.
  1564.  
  1565.     This function queries the status of a slot.
  1566.  
  1567.     Parameters
  1568.     
  1569.     sndnum is the sound's unique ID.
  1570.  
  1571.     result is a pointer to a variable to hold the returned status: 
  1572.  
  1573.     0                                         //no sound with this ID
  1574.     dws_DSTATUSCURRENT                        //sound is currently playing
  1575.     dws_DSTATUSSEQUENCED                      //sound is sequenced
  1576.     dws_DSTATUSCURRENT | dws_DSTATUSSEQUENCED //both
  1577.  
  1578.     For a slot to contain a sequenced sound, it must also hold a
  1579.     playing sound.  If you ever encounter a case where a slot
  1580.     contains only a sequenced sound, please report it to
  1581.     DiamondWare.
  1582.  
  1583.     Return value
  1584.  
  1585.     Boolean success.
  1586.  
  1587.     See also
  1588.  
  1589.     dws_DPlay
  1590.  
  1591.     Errors
  1592.  
  1593.     dws_NOTINITED, dws_NOTSUPPORTED
  1594.  
  1595. dws_DUnPause
  1596.  
  1597.     Prototypes
  1598.  
  1599.     word dws_DUnPause(void);
  1600.     function dws_DUnPause : word;
  1601.     DECLARE FUNCTION dwsDUnPause% ALIAS "DWS_DUNPAUSE" ()
  1602.  
  1603.     Description
  1604.  
  1605.     This function resumes digitized playback, if it was previously
  1606.     paused by dws_DPause.
  1607.  
  1608.     All sounds will continue where they left off.
  1609.  
  1610.     Note: all calls after the first will have no effect until
  1611.     dws_DPause is called again.  The STK does not maintain a "pause
  1612.     count".
  1613.  
  1614.     Parameters
  1615.  
  1616.     None.
  1617.  
  1618.     Return value
  1619.  
  1620.     Boolean success.
  1621.  
  1622.     See also
  1623.  
  1624.     dws_DPause
  1625.  
  1626.     Errors
  1627.  
  1628.     dws_NOTINITED, dws_NOTSUPPORTED
  1629.  
  1630. dws_ErrNo
  1631.  
  1632.     Prototypes
  1633.  
  1634.     word dws_ErrNo(void);
  1635.     function dws_ErrNo : word;
  1636.     DECLARE FUNCTION dwsErrNo% ALIAS "DWS_ERRNO" ()
  1637.  
  1638.     Description
  1639.     
  1640.     This function returns the last error triggered by an STK
  1641.     function.  Call it after any STK function returns false as its
  1642.     boolean success indicator.
  1643.  
  1644.     Successful STK calls do not affect the return value of dws_ErrNo.
  1645.  
  1646.     Parameters
  1647.  
  1648.     None.
  1649.  
  1650.     Return value
  1651.     
  1652.     The last STK error.
  1653.  
  1654.     See also
  1655.  
  1656.     None.
  1657.  
  1658.     Errors
  1659.  
  1660.     None.
  1661.  
  1662. dws_Init
  1663.  
  1664.     Prototypes
  1665.  
  1666.     word dws_Init(dws_DETECTRESULTS *dr, dws_IDEAL *ideal); function
  1667.     dws_Init(dr : dws_DRPTR; ideal : dws_IDPTR) : word; DECLARE
  1668.         FUNCTION
  1669.     dwsInit% ALIAS "DWS_INIT" (SEG dr AS dwsDETECTRESULTS, SEG ideal
  1670.         AS dwsIDEAL)
  1671.  
  1672.     Description
  1673.  
  1674.     This function configures and initializes the hardware and the
  1675.     STK internals.  Most STK calls won't work until after this call.
  1676.  
  1677.     The exceptions are dws_Update, dws_DetectHardware, dws_ErrNo,
  1678.     and dws_DGetRateFromDWD.
  1679.  
  1680.     Parameters
  1681.     
  1682.     dr is a pointer to a dws_DETECTRESULTS struct that has been
  1683.     filled in by a call to dws_DetectHardware.
  1684.  
  1685.     ideal is a pointer to a dws_IDEAL structure, which you must fill
  1686.     in with your requested settings.  The programmer might not want
  1687.     the user's sound board running to its limit, and/or the user's
  1688.     sound board may not support every feature of the STK.
  1689.  
  1690.     Note: the STK supports sample rates from 4 KHz to 24 KHz.
  1691.  
  1692.     Return value
  1693.     
  1694.     Boolean success.
  1695.  
  1696.     See also
  1697.  
  1698.     dws_DetectHardware, dws_Kill, dws_Update
  1699.  
  1700.     Errors
  1701.  
  1702.     dws_ALREADYINITTED
  1703.  
  1704. dws_Kill
  1705.  
  1706.     Prototypes
  1707.  
  1708.     word dws_Kill(void);
  1709.     function dws_Kill : word;
  1710.     DECLARE FUNCTION dwsKill% ALIAS "DWS_KILL"()
  1711.  
  1712.     Description
  1713.  
  1714.     This function closes down the STK.  You must call it before your
  1715.     program terminates.
  1716.  
  1717.     Note: make sure you cover every exit path from your program,
  1718.     including DOS critical errors!  Failure to do so will leave the
  1719.     machine in a bad state.  The sound board will make noise
  1720.     forever.  The DMA controller will continue transferring.  The
  1721.     sound hardware will continue to generate IRQ's.  When the next
  1722.     program is loaded, it will overwrite the STK's Interrupt Service
  1723.     Routine (ISR)--and the machine will crash.
  1724.  
  1725.     Parameters
  1726.  
  1727.     None.
  1728.  
  1729.     Return value
  1730.     
  1731.     Boolean success.
  1732.  
  1733.     See also
  1734.  
  1735.     dws_Init, dws_DetectHardware, dws_Update
  1736.  
  1737.     Errors
  1738.  
  1739.     dws_NOTINITTED, dws_Kill_CANTUNHOOKISR
  1740.  
  1741.     If the STK can't unhook its ISR, it probably means the user
  1742.     installed a TSR which handles the sound board's IRQ.  Whatever
  1743.     it accomplished(?), it's now preventing the STK from properly
  1744.     unhooking itself.  Tell the user to get rid of it, and call
  1745.     dws_Kill again.
  1746.  
  1747. dws_MClear
  1748.  
  1749.     Prototypes
  1750.  
  1751.     word dws_MClear(void);
  1752.     function dws_MClear : word;
  1753.     DECLARE FUNCTION dwsMClear% ALIAS "DWS_MCLEAR" ()
  1754.  
  1755.     Description
  1756.  
  1757.     This function stops music playback.
  1758.  
  1759.     Parameters
  1760.         
  1761.     None.
  1762.  
  1763.     Return value
  1764.     
  1765.     Boolean success.
  1766.  
  1767.     See also
  1768.  
  1769.     dws_MPause, dws_MPlay
  1770.  
  1771.     Errors
  1772.  
  1773.     dws_NOTINITED, dws_NOTSUPPORTED
  1774.  
  1775. dws_MPause
  1776.  
  1777.     Prototypes
  1778.  
  1779.     word dws_MPause(void);
  1780.     function dws_MPause : word;
  1781.     DECLARE FUNCTION dwsMPause% ALIAS "DWS_MPAUSE" ()
  1782.  
  1783.     Description
  1784.  
  1785.     This function pauses music playback.
  1786.  
  1787.     Note: all calls after the first will have no effect until
  1788.     dws_MUnPause is called.  The STK does not maintain a "pause
  1789.     count".
  1790.  
  1791.     Parameters
  1792.     
  1793.     None.
  1794.  
  1795.     Return value
  1796.  
  1797.     Boolean success.
  1798.  
  1799.     See also
  1800.  
  1801.     dws_MUnPause, dws_MClear, dws_MPlay
  1802.  
  1803.     Errors
  1804.  
  1805.     dws_NOTINITED, dws_NOTSUPPORTED
  1806.  
  1807. dws_MPlay
  1808.  
  1809.     Prototypes
  1810.  
  1811.     word dws_MPlay(dws_MPLAY *mplay);
  1812.     function dws_MPlay(mplay : dws_MPPTR) : word;
  1813.     DECLARE FUNCTION dwsMPlay% ALIAS "DWS_MPLAY" (SEG mplay AS
  1814.         dwsMPLAY)
  1815.  
  1816.     Description
  1817.  
  1818.     This function starts playing a song.
  1819.  
  1820.     Parameters
  1821.  
  1822.     mplay is a pointer to a dws_MPLAY struct, which you must fill
  1823.     in.  The fields are:
  1824.  
  1825.     track   pointer to a buffer which contains a .DWM file.
  1826.     count   number of times to play; 0 means repeat indefinitely.
  1827.  
  1828.     Return value
  1829.  
  1830.     Boolean success.
  1831.  
  1832.     See also
  1833.  
  1834.     dws_MClear, dws_MPause, dws_MSongStatus
  1835.  
  1836.     Errors
  1837.  
  1838.     dws_NOTINITED, dws_NOTSUPPORTED, dws_MPlay_NOTADWM, 
  1839.     dws_MPlay_NOTSUPPORTEDVER, dws_MPlay_INTERNALERROR
  1840.  
  1841. dws_MSongStatus
  1842.  
  1843.     Prototypes
  1844.  
  1845.     word dws_MSongStatus(word *status);
  1846.     function dws_MSongStatus(result : dws_WDPTR) : word;
  1847.     DECLARE FUNCTION dwsMSongStatus% ALIAS = "DWS_MSONGSTATUS" (SEG
  1848.         result%)
  1849.  
  1850.     Description
  1851.  
  1852.     This function returns the status of the music playback engine.
  1853.  
  1854.     Parameters
  1855.  
  1856.     result is a pointer to a variable to hold the returned status:
  1857.  
  1858.     0                                              //no song loaded
  1859.     dws_MSONGSTATUSPLAYING                         //song playing
  1860.     dws_MSONGSTATUSPAUSED                          //no song loaded,
  1861.                                                      STK paused
  1862.     dws_MSONGSTATUSPLAYING | dws_MSONGSTATUSPAUSED //Song loaded but
  1863.                                                      paused
  1864.  
  1865.     Return value
  1866.  
  1867.     Boolean success.
  1868.  
  1869.     See also
  1870.  
  1871.     dws_MPlay
  1872.  
  1873.     Errors
  1874.  
  1875.     dws_NOTINITED, dws_NOTSUPPORTED
  1876.  
  1877. dws_MUnPause
  1878.  
  1879.     Prototypes
  1880.  
  1881.     word dws_MUnPause(void);
  1882.     function dws_MUnPause : word;
  1883.     DECLARE FUNCTION dwsMUnPause% ALIAS "DWS_MUNPAUSE" ()
  1884.  
  1885.     Description
  1886.     
  1887.     This function unpauses music paused by dws_MPause.  The music
  1888.     will continue where it left off, save that any sustaining notes
  1889.     will not start until their next key on.
  1890.  
  1891.     Note: all calls after the first will have no effect until
  1892.     dws_MPause is called again.  The STK does not maintain a "pause
  1893.     count".
  1894.  
  1895.     Parameters
  1896.  
  1897.     None.
  1898.  
  1899.     Return value
  1900.  
  1901.     Boolean success.
  1902.  
  1903.     See also
  1904.  
  1905.     dws_MPause
  1906.  
  1907.     Errors
  1908.  
  1909.     dws_NOTINITED, dws_NOTSUPPORTED
  1910.  
  1911. dws_Update
  1912.  
  1913.     Prototypes
  1914.  
  1915.     void __loadds __saveregs dws_Update(void);
  1916.     procedure dws_Update;
  1917.     SUB dwsUpdate ALIAS "DWS_UPDATE" ()
  1918.  
  1919.     Description
  1920.  
  1921.     This function keeps the STK going.  Call it regularly and frequently.
  1922.  
  1923.     If you're using the DWT, don't call dws_Update!  Everything has
  1924.     been taken care of.
  1925.  
  1926.     If you are using your own timer handler, you need to call
  1927.     dws_Update every time you get your interrupt.  dws_Update will
  1928.     load the registers it needs, and restore the caller's registers
  1929.     before returning.  Note that this function is to be called, not
  1930.     jumped to.  It returns with a retf, not an iret.
  1931.  
  1932.     Parameters
  1933.  
  1934.     None.
  1935.  
  1936.     Return value
  1937.  
  1938.     None.
  1939.  
  1940.     See also
  1941.  
  1942.     dws_Init, dwt_Init, dws_Kill, dwt_Kill
  1943.  
  1944.     Errors
  1945.  
  1946.     None
  1947.  
  1948. dws_XDig
  1949.  
  1950.     Prototypes
  1951.  
  1952.     word dws_XDig(word volume);
  1953.     function dws_XDig(volume : word) : word;
  1954.     DECLARE FUNCTION dwsXDig% ALIAS "DWS_XDIG" (BYVAL volume%)
  1955.  
  1956.     Description
  1957.     
  1958.     This function sets the digitized volume of the mixer.
  1959.  
  1960.     Note: dws_Init sets the digital volume to maximum.
  1961.  
  1962.     Parameters
  1963.  
  1964.     volume is the digitized sound level (0=min, 255=max).
  1965.  
  1966.     Return value
  1967.     
  1968.     Boolean success.
  1969.  
  1970.     See also
  1971.  
  1972.     dws_XMusic, dws_XMaster
  1973.  
  1974.     Errors
  1975.  
  1976.     dws_NOTINITTED, dws_NOTSUPPORTED, dws_X_BADINPUT
  1977.  
  1978. dws_XMaster
  1979.  
  1980.     Prototypes
  1981.  
  1982.     word dws_XMaster(word volume);
  1983.     function dws_XMaster(volume : word) : word;
  1984.     DECLARE FUNCTION dwsXMaster% ALIAS "DWS_XMASTER" (BYVAL volume%)
  1985.  
  1986.     Description
  1987.  
  1988.     This function sets the overall volume of the mixer.
  1989.  
  1990.     Note: dws_Init sets the master volume to maximum.
  1991.  
  1992.     Parameters
  1993.     
  1994.     volume is the master sound level (0=min, 255=max).
  1995.  
  1996.     Return value
  1997.     
  1998.     Boolean success.
  1999.  
  2000.     See also
  2001.  
  2002.     dws_XDig, dws_XMusic
  2003.  
  2004.     Errors
  2005.  
  2006.     dws_NOTINITTED, dws_NOTSUPPORTED, dws_X_BADINPUT
  2007.  
  2008. dws_XMusic
  2009.  
  2010.     Prototypes
  2011.  
  2012.     word dws_XMusic(word volume);
  2013.     function dws_XMusic(volume : word) : word;
  2014.     DECLARE FUNCTION dwsXMusic% ALIAS "DWS_XMUSIC" (BYVAL volume%)
  2015.  
  2016.     Description
  2017.  
  2018.     This function sets the music volume of the mixer.
  2019.  
  2020.     Note: dws_Init sets the music volume to maximum.
  2021.  
  2022.     Parameters
  2023.  
  2024.     volume is the music sound level (0=min, 255=max).
  2025.  
  2026.     Return value
  2027.  
  2028.     Boolean success.
  2029.  
  2030.     See also
  2031.  
  2032.     dws_XDig, dws_XMaster
  2033.  
  2034.     Errors
  2035.  
  2036.     dws_NOTINITTED, dws_NOTSUPPORTED, dws_X_BADINPUT
  2037.  
  2038. dwt_Init
  2039.  
  2040.     Prototypes
  2041.  
  2042.     void dwt_Init(word rate);
  2043.     procedure dwt_Init(rate : word);
  2044.     DECLARE SUB dwtInit ALIAS "DWT_INIT" (BYVAL rate%)
  2045.  
  2046.     Description
  2047.  
  2048.     This function initializes the timer hardware and DWT internals.
  2049.  
  2050.     Call this only if you're using the DWT.  Use the DWT only if you
  2051.     aren't reprogramming the hardware timer.
  2052.  
  2053.     None of the DWT functions will work until this function is called.
  2054.  
  2055.     Parameters
  2056.     
  2057.     rate is one of the four constants:
  2058.         dwt_18_2HZ
  2059.         dwt_36_4HZ
  2060.         dwt_72_8HZ
  2061.         dwt_145_6HZ
  2062.  
  2063.     Return value
  2064.  
  2065.     None.
  2066.  
  2067.     See also
  2068.  
  2069.     dws_Update, dwt_Kill, dwt_MasterTick
  2070.  
  2071. dwt_Kill
  2072.  
  2073.     Prototypes
  2074.  
  2075.     void dwt_Kill(void);
  2076.     procedure dwt_Kill;
  2077.     DECLARE SUB dwtKill ALIAS "DWT_KILL" ()
  2078.  
  2079.     Description
  2080.     
  2081.     This function closes down the DWT.  If you used the DWT, you
  2082.     must call dwt_Kill before your program terminates.
  2083.  
  2084.     Note: make sure you cover every exit path from your program,
  2085.     including DOS critical errors!  Failure to do so will leave the
  2086.     machine in a bad state.  When the next program is loaded, it
  2087.     will overwrite the DWT's Interrupt Service Routine (ISR)--and
  2088.     the machine will crash.
  2089.  
  2090.     Parameters
  2091.  
  2092.     None.
  2093.  
  2094.     Return value
  2095.  
  2096.     None.
  2097.  
  2098.     See also
  2099.  
  2100.     dws_Update, dwt_Init
  2101.  
  2102. dwt_MasterTick
  2103.  
  2104.     Prototypes
  2105.  
  2106.     dword dwt_MasterTick(void);
  2107.     dwt_MasterTick : longint;
  2108.     DECLARE FUNCTION dwtMasterTick& ALIAS "DWT_MASTERTICK" ()
  2109.  
  2110.     Description
  2111.     
  2112.     This function queries the value of the master timer.
  2113.  
  2114.     The master timer is reset to 0 in dwt_Init, and is incremented
  2115.     at the DWT timer rate.
  2116.  
  2117.     Parameters
  2118.  
  2119.     None.
  2120.  
  2121.     Return value
  2122.     
  2123.     Number of clock ticks since DWT was initialized.
  2124.  
  2125.     See also
  2126.  
  2127.     dwt_Init, dwt_Pause, dwt_UnPause
  2128.  
  2129. dwt_Pause
  2130.  
  2131.     Prototypes
  2132.  
  2133.     void dwt_Pause(void);
  2134.     procedure dwt_Pause;
  2135.     DECLARE SUB dwtPause ALIAS "DWT_INIT" ()
  2136.  
  2137.     Description
  2138.     
  2139.     This function pauses the master timer.
  2140.  
  2141.     Note: this does not effect music or sound playback.
  2142.  
  2143.     Note: all calls after the first will have no effect until
  2144.     dwt_UnPause is called.  The DWT does not maintain a "pause
  2145.     count".
  2146.  
  2147.     Parameters
  2148.     
  2149.     None.
  2150.  
  2151.     Return value
  2152.     
  2153.     None.
  2154.  
  2155.     See also
  2156.  
  2157.     dwt_MasterTick, dwt_UnPause
  2158.  
  2159. dwt_UnPause
  2160.  
  2161.     Prototypes
  2162.  
  2163.     void dwt_UnPause(void);
  2164.     procedure dwt_UnPause;
  2165.     DECLARE SUB dwtUnPause ALIAS "DWT_KILL" ()
  2166.  
  2167.     Description
  2168.     
  2169.     This function unpauses the master timer, if it was previously
  2170.     paused by dwt_Pause.
  2171.  
  2172.     Note: all calls after the first will have no effect until
  2173.     dwt_Pause is called again.  The STK does not maintain a "pause
  2174.     count"
  2175.  
  2176.     Parameters
  2177.     
  2178.     None.
  2179.  
  2180.     Return value
  2181.     
  2182.     None.
  2183.  
  2184.     See also
  2185.  
  2186.     dwt_Pause, dwt_MasterTick
  2187.         
  2188.                                The Errors
  2189.  
  2190. About the Error Listing
  2191. -----------------------
  2192. This section discusses every possible STK error in numerical order.
  2193. See The Functions to find the complete list of errors which may be
  2194. flagged by any given function.
  2195.  
  2196. 0.  dws_EZERO
  2197. There was no error.  You didn't need to call dws_ErrNo.
  2198.  
  2199. 1.  dws_NOTINITTED
  2200. The STK was not initialized when you called an STK function.
  2201.  
  2202. 2.  dws_ALREADYINITTED
  2203. This call cannot be made after the STK is initialized.
  2204.  
  2205. 3.  dws_NOTSUPPORTED
  2206. The installed hardware doesn't support the requested feature (music
  2207. or sound).
  2208.  
  2209. 4. dws_DetectHardware_UNSTABLESYSTEM
  2210. This system is now unstable.  Please report this to DiamondWare.
  2211.  
  2212. 5. dws_DetectHardware_BADBASEPORT
  2213. 6. dws_DetectHardware_BADDMA
  2214. 7. dws_DetectHardware_BADIRQ
  2215. You tried to override the autodetect with an irrational value for
  2216. base port, DMA channel, or IRQ level, respectively.
  2217.  
  2218. 8.  dws_Kill_CANTUNHOOKISR
  2219. After the STK initialized, the user installed a TSR which hooked the
  2220. sound board's interrupt vector.  The STK can't shut down cleanly.
  2221. Tell the user to kill the TSR.  Then call dws_Kill again.
  2222.  
  2223. 9.  dws_X_BADINPUT
  2224. You attempted to set a mixer level (digitized, music, or master) to
  2225. a value outside the range 0-255.
  2226.  
  2227. 10.  dws_D_NOTADWD
  2228. The buffer does not contain a valid .DWD file.
  2229.  
  2230. 11.  dws_D_NOTSUPPORTEDVER
  2231. This .DWD file is the wrong version.  Please reconvert using the
  2232. VOC2DWD which came with this version of the STK.
  2233.  
  2234. 12.  dws_D_INTERNALERROR
  2235. The STK encountered an invalid internal state.  Please report this
  2236. to DiamondWare.
  2237.  
  2238. 13.  dws_DPlay_NOSPACEFORSOUND
  2239. You attempted to play a low-priority sound, but all slots were in
  2240. use.  Try increasing ideal.dignvoices.  If this error occurs with
  2241. that set to 16, you're playing too many sounds too fast.  Note: this
  2242. one is a warning.  It's reasonable to flag this error occasionally.
  2243. But if it occurs immediately, or consistently, try calling dws_DPlay
  2244. less often.
  2245.  
  2246. 14.   dws_DSetRate_FREQTOLOW
  2247. 15. dws_DSetRate_FREQTOHIGH
  2248. You attempted to set the sampling rate to an invalid frequency.  The
  2249. STK supports sampling rates from 4 KHz to 24 KHz.
  2250.  
  2251. 16.  dws_MPlay_NOTADWM
  2252. The buffer does not contain a valid .DWM file.
  2253.  
  2254. 17.  dws_MPlay_NOTSUPPORTEDVER
  2255. This .DWM file is the wrong version.  Please reconvert using the
  2256. MID2DWM which came with this version of the STK.
  2257.  
  2258. 18.  dws_MPlay_INTERNALERROR
  2259. The STK encountered an invalid internal state.  Please report this
  2260. to DiamondWare.
  2261.  
  2262.                         The Data Structures
  2263.  
  2264. Preamble
  2265. --------
  2266. In this section, the data structures are laid out in table form.
  2267. This is done in the hope that it's easier to read than compiler
  2268. declarations.  Obviously, you can read the actual source files if
  2269. you wish.
  2270.  
  2271. Note to Pascal programmers: the following types were created to
  2272. allow the declaration of subroutines which take far pointers to
  2273. their parameters.  Declaring a function:
  2274.  
  2275. function FooBar(var x: word);
  2276.  
  2277. passes a near pointer.  The STK expects far pointers.
  2278.  
  2279. dws_DOPTR = ^dws_DETECTOVERRIDES;
  2280. dws_DRPTR = ^dws_DETECTRESULTS;
  2281. dws_IDPTR = ^dws_IDEAL;
  2282. dws_DPPTR = ^dws_DPLAYREC;
  2283. dws_MPPTR = ^dws_MPLAYREC;
  2284. dws_WDPTR = ^word;
  2285. dws_BTPTR = ^byte;
  2286.  
  2287.  
  2288. The dws_DETECTOVERRIDES struct
  2289.  
  2290. Name      Size    I/O     Description
  2291. ------------------------------------------------------
  2292. baseport  2       input   base address of sound board
  2293. digdma    2       input   DMA channel
  2294. digirq    2       input   IRQ level
  2295. reserved  10      -na-    undocumented
  2296.  
  2297.  
  2298. The dws_DETECTRESULTS struct
  2299.  
  2300. Name        Size    I/O     Description
  2301. -------------------------------------------------------------
  2302. baseport    2       output  base address of sound board
  2303. capability  2       output  bitfield of supported features
  2304. mustyp      2       output  0=none, 1=OPL2
  2305. musnchan    2       output  *1=mono
  2306. musnvoice   2       output  *number of melody voices
  2307. dignbits    2       output  +8=8 bits
  2308. dignchan    2       output  +1=mono
  2309. digdma      2       output  +digitized DMA channel
  2310. digirq      2       output  +digitized IRQ level
  2311. mixtyp      2       output  mixer type (1 software, 2+ H/W)
  2312. reserved    44      -na-    undocumented
  2313.  
  2314. * if (capability & dws_capability_FM)
  2315. + if (capability & dws_capability_DIG)
  2316.  
  2317. The dws_IDEAL struct
  2318.  
  2319. Name        Size    I/O     Description
  2320. ----------------------------------------------------------------
  2321. musictyp    2       input   music type (0 none, 1 FM)
  2322. digtyp      2       input   digitzed type (0 none, 8 8-bit dig)
  2323. digrate     2       input   sampling rate, in Hz
  2324. dignvoices  2       input   number of voices (up to 16)
  2325. dignchan    2       input   1=mono
  2326. reserved    6       -na-    undocumented
  2327.  
  2328.  
  2329. The dws_DPLAY struct
  2330.  
  2331. Name      Size      I/O       Description
  2332. -----------------------------------------------------------------
  2333. snd       4         input     pointer to buffer with .DWD in it
  2334. count     2         input     # times to play (0=infinite loop)
  2335. priority  2         input     higher numbers are higher priority
  2336. presnd    2         input     soundnum to sequence after
  2337. soundnum  2         output    unique ID
  2338. reserved  20        -na-      undocumented
  2339.  
  2340.  
  2341. The dws_MPlay struct
  2342.  
  2343. Name      Size      I/O       Description
  2344. ----------------------------------------------------------------
  2345. track     4         input     pointer to buffer with .DWM in it
  2346. count     2         input     # times to play (0=infinite loop)
  2347. reserved  10        -na-      undocumented
  2348.  
  2349.                          The Utilities
  2350.  
  2351. PLAYDWM
  2352. -------
  2353. PLAYDWM is a simple program to play .DWM music files.  Full source
  2354. is included with the STK.  Usage is:
  2355.  
  2356. PLAYDWM songname.dwm
  2357.  
  2358. You must type the full filename, including the .DWM.
  2359.  
  2360. PLAYDWD
  2361. -------
  2362. PLAYDWD is a simple program to play .DWD sound effect files.  Full
  2363. source is included with the STK.  Usage is:
  2364.  
  2365. PLAYDWD soundfx.dwd
  2366.  
  2367. You must type the full filename, including the .DWD.
  2368.  
  2369. FINDSB
  2370. ------
  2371. FINDSB is provided as both a simple example of how to use the STK,
  2372. and as a useful program in its own right.  Full source is included
  2373. with the STK.  It will find and print out the user's sound board
  2374. settings.  Usage is:
  2375.  
  2376.      FINDSB
  2377.  
  2378. MID2DWM
  2379. -------
  2380. MID2DWM converts type 1 standard MIDI files from .MID format to .DWM
  2381. format.  It is strictly a command-line utility.  Usage is:
  2382.  
  2383. MID2DWM <<rate>> <<midifile>>[.MID] <<instrfile>>[.IBK] [outfile
  2384. [.DWM]]
  2385.  
  2386. rate is the frequency, at which STK will get its "heartbeat" call
  2387. during run-time.  In general, the higher the rate, the more natural
  2388. the music will sound (to a limit).  If your music was performed by a
  2389. human, there are many nuances of timing which will be lost at lower
  2390. rates.
  2391.  
  2392. Note: if your program is running in a Windows DOS box, 145.6 Hz will
  2393. not work correctly (Windows will simply refuse to call you that
  2394. fast, and so the music will play slower than normal).
  2395.  
  2396. The STK includes an optional timer module which is capable of four
  2397. rates: 18.2, 36.4, 72.8, and 145.6 Hz.  If you use your own timer
  2398. code, then tell MID2DWM the rate it runs at; MID2DWM will work at
  2399. any rate.  If you're using the code supplied in the STK, use one of
  2400. those four rates only.
  2401.  
  2402. midifile is the name of the source file for the music, in MIDI type
  2403. 1 format.  The extension, .MID, is optional.
  2404.  
  2405. instrfile is the name of the instrument patch bank file, in .IBK
  2406. format.  The extension, .IBK, is optional.
  2407.  
  2408. outfile is an optional parameter, to specify the name of the output
  2409. file (if different from the source file).  The extension, .DWM, is
  2410. optional.
  2411.  
  2412. As a simple matter of managing the hundreds of files in your
  2413. project, if you keep the default file extensions for each type of
  2414. file, you'll make your life easier.
  2415.  
  2416. Examples:
  2417.  
  2418. C:\SOURCE\BANE\MUSIC mid2dwm 72.8 death gmptch
  2419. C:\SOURCE\BANE\MUSIC mid2dwm 36.4 death.mid gmptch.ibk dth1.dwm
  2420.  
  2421. MID2DWM can convert, and the STK can play, music files larger than
  2422. 64K.
  2423.  
  2424. VOC2DWD
  2425. -------
  2426. VOC2DWD converts digitized sound files from .VOC format to .DWD
  2427. format.  It is strictly a command-line utility.  Usage is:
  2428.  
  2429. VOC2DWD <<vocfile>>[.VOC] [outfile [.DWD]]
  2430.  
  2431. vocfile is the filename of the input file, which must be in VOC
  2432. format.  The extension, .VOC, is optional.
  2433.  
  2434. outfile is an optional parameter which specifies the name of the
  2435. output file, if different from the input file.  The .DWD extension
  2436. is optional.
  2437.  
  2438. Examples:
  2439.  
  2440. C:\SOURCE\BANE\SFX voc2dwd scream
  2441. C:\SOURCE\BANE\SFX voc2dwd scream.voc sc1.dwd
  2442.  
  2443. You can use DOS wildcards to specify vocfile, as in:
  2444.  
  2445. C:\SOURCE\BANE\SFX voc2dwd *.voc
  2446.  
  2447. VOC2DWD will allow you to convert files greater than 64K; however,
  2448. this version of the STK will not play them back.  A sequencing
  2449. mechanism is offered to allow you to play long sounds, but they must
  2450. be broken up while they're in .VOC format.
  2451.  
  2452. Although .VOC files can support all sampling rates via "extended
  2453. blocks", some .VOC editors only save standard blocks.  These blocks
  2454. round to the nearest encodable rate, which can be off by up to 1
  2455. KHz.  For example, an 11 KHz .VOC file will be saved at 10989 Hz if
  2456. the sound editor only supports standard blocks.  A difference of 11
  2457. Hz is negligible to the human ear, but 1000 Hz (which happens at
  2458. higher rates) is not.  VOC2DWD supports both kinds of blocks, and
  2459. reports the true sampling rate during the conversion to help combat
  2460. this problem.
  2461.  
  2462.                        Ordering Information
  2463.  
  2464. DiamondWare's Sound ToolKit is available from the following authorized
  2465. distributors:
  2466.  
  2467. In the United States:
  2468. --------------------
  2469. MVP Software
  2470. 1035 Dallas SE
  2471. Grand Rapids, MI 49507-1407
  2472. phone: 800-968-9684 24-hour order line only
  2473.        (616) 245-8376 information, technical support, or orders.
  2474. fax: (616) 245-3204
  2475.  
  2476. order price: $299.95 plus $4.00 shipping in the United States; $5.00
  2477. shipping to Canada; $6.00 shipping everywhere else.  Michigan residents
  2478. please add $18.24 sales tax.
  2479.  
  2480. In Australia:
  2481. ------------
  2482. Budgetware
  2483. 9 Albermarle St
  2484. Newtown NSW 2042
  2485. phone: (02) 519-4233           fax: (02) 516-4236
  2486. call for current price
  2487.  
  2488. In the United Kingdom:
  2489. ---------------------
  2490. Oakley Data Services
  2491. 3, Oakley Close
  2492. Sandbach
  2493. Cheshire CW11 9RQ
  2494.  
  2495. phone: (0) 1270 759739         fax: (0) 1270 765272
  2496. email 74774,1347@compuserve.com
  2497. call for current price
  2498.  
  2499. In Denmark and all of Scandanavia:
  2500. ---------------------------------
  2501. Pro-Soft
  2502. Benloese Skel 4 G
  2503. DK 4100 Ringsted
  2504.  
  2505. phone: 53 61 90 42             fax: 53 61 93 91
  2506. call for current price
  2507.  
  2508. In Japan:
  2509. --------
  2510. P. & A. Company Ltd
  2511. 302 Bellwins, 1367-23
  2512. Nakagami, Akishima
  2513. Tokyo 196
  2514.  
  2515. phone: 425-46-9141             fax: 425-46-9142
  2516. BBS: 425-46-9143
  2517. call for current price
  2518.  
  2519. Germany, Austria, and Switzerland
  2520. ---------------------------------
  2521. JDS -- Software Vertrieb
  2522. Jens Driese
  2523. Postfach 1269
  2524. D-26302
  2525.  
  2526. phone: 04451-85743             fax: 04451-860500
  2527. CIS: 100273,2252               BTX: DRIESE#
  2528. call for current price
  2529.  
  2530. The Netherlands
  2531. ---------------
  2532. HaSa Software Applications
  2533. PO Box 414
  2534. 9500 AK Stadskanaal
  2535.  
  2536. phone: 5990 50161                  fax: 5990 50124
  2537. BBS: 5990 50212 or 50314 or 50232  CIS: 100115,542
  2538. call for current price
  2539.  
  2540. Italy
  2541. -----
  2542. Systems Comunicazioni srl
  2543. via Olanda
  2544. 6 - 20083 Gaggiano
  2545.  
  2546. phone: (02) 9084 1814              fax: (02) 9084 1682
  2547. BBS: (02) 9084 1811
  2548. call for current price
  2549.  
  2550.                   DiamondWare's Sound ToolKit Order Form
  2551.  
  2552. Name ________________________________________________________________
  2553.  
  2554. Address _____________________________________________________________
  2555.  
  2556. City _______________________________ State ______ ZIP _______________
  2557.  
  2558. Country (if outside USA) ____________________________________________
  2559.  
  2560. Price of DiamondWare's Sound ToolKit                              $299.95
  2561. Shipping and Handling in the US                                      4.00
  2562. Shipping and Handling to Canada                                      5.00
  2563. Shipping and Handling to other countries                             6.00
  2564. Michigan residents sales tax                                   add $18.24
  2565.  
  2566. Make check payable to "MVP Software"         Total enclosed:  $__________
  2567.  
  2568. Master Card/Visa information (credit card orders only)
  2569. Card number __________________________________________ Expiration _________
  2570. ---------------------------------------------------------------------------
  2571. VOLUNTARY QUESTIONS:  Please help us determine what features you would like
  2572. ====================  in upgrades and future products.
  2573.  
  2574. Circle what type of equipment you have: 286    386    486    Pentium    P6
  2575. Circle the speed of your computer(Mhz): 16  20  25  33  40  50  66  90 ___
  2576. Circle any that apply: Joystick  Mouse  Modem_______  SVGA card____________
  2577.                                              (speed)              (type)
  2578.  
  2579. Where did you get the demo of DiamondWare's Sound ToolKit?
  2580.     Friend   CompuServe   AOL   Ryan's Bar   Exec-PC   Sound Advice
  2581.     Invention Factory   Channel 1   Space BBS   World Data Network
  2582.     BBS (name): _______________________
  2583.     Shareware Distributor (name): _________________________________________
  2584.     address _______________________________________________________________
  2585.  
  2586. What new features would you like to see added to the STK?
  2587.  
  2588.  
  2589.  
  2590. ---------------------------------------------------------------------------
  2591. Send this order form and your check to:
  2592.  
  2593. MVP Software, 1035 Dallas S.E., Grand Rapids, MI  49507-1407
  2594.  
  2595. From the US or Canada call 800-968-9684 toll-free 24-hour order line.
  2596. Call (616) 245-8376 tech support, information, or overseas orders.
  2597.  
  2598.